Text of discuss.python.org › t › cleaning-up-packaging-python-org-guides › 16717 as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Cleaning up packaging.python.org guides - Packaging - Discussions on Python.org

Cleaning up packaging.python.org guides Packaging documentation henryiii (Henry Schreiner) June 21, 2022, 7:51pm 1 Currently there are a lot of guides on packaging.python.org . Many of them are quite outdated, and a significant number of them probably just don’t need to exist anymore, I think. It might really help to go through and “hide” some of the useless pages (guessing the URL could be kept alive, just it would not be linked anywhere?) or replace them with a page with different content but the same URL, etc.

Some ideas for removable pages: Migrating to PyPI.org 2016 advice Supporting Windows using Appveyor A single CI service guide from 2015 telling users how to setup Python 3.3 Multi-version installs How to use easy_install & pkg_resources to do… something. Supporting multiple Python versions Basically a list of how to support Python 2 & 3 at the same time. I’d also like to continue (slowly) to adapt to modern standards, which makes the following pages a bit too specific.

Some of them probably should be moved to or used to update setuptools docs before being generalized. Including files in source distributions with MANIFEST.in - this should be more general, but hard because source file handling is not standard. I think this is the only one with a potentially bad title/link (Manifest.in) Single-sourcing the package version - Very classic setuptools specific Dropping support for older Python versions - easy to generalize / update via PEP 621 Creating and discovering plugins Probably easy to generalize via PEP 621 I’m seeing other even smaller things that should be easy to update.

But those are the biggest ones that would require page-level updates. Probably worth a second topic, but it might be really nice to have a “goal” (like the fixme/todos) to specify what we’d like the pages to become and encourage users to updates. I’m a fan of small, easy-to-review incremental PRs over one massive one that takes 6 months to merge (but sometimes can’t be avoided). Would PRs removing the pages listed in the first list, and PRs updating the second list be a good idea?

Ideas on keeping old URLs, or does it not matter? 12 Likes JDLH (Jim DeLaHunt) June 21, 2022, 8:38pm 2 This cleanup is a great idea. As a novice, I can tell you that all this obsolete stuff is distracting from the task of learning what works today. I am against letting any existing URL turn into an error 404. Eventually, we can replace some of the documents there with a new document which covers the same material. Right now, we can put a big label at the top of the document which says it is obsolete.

I would suggest a first PR or PRs is one which applies “obsolete” labels to all the above documents. Another good PR is one which reorders the top page of packaging.python.org so that the links to these documents are under a heading “obsolete”, and/or the link texts to each get some indicator of “obsolete”. 5 Likes henryiii (Henry Schreiner) June 21, 2022, 9:12pm 3 Is there a way to simply not show up in the navigation at all?

There could be a page or sitemap type thing that still gets to them (or not), but no need to have them linked from the main navigation, I think. That’s the point of my ordering above, the ones that don’t have a replacement are in the first category, and ones needing big updates or replacement are in the second one. I like this idea. brettcannon (Brett Cannon) June 21, 2022, 9:33pm 4 As in the Table of Contents like packaging.python.org/source/index.rst at main · pypa/packaging.python.org · GitHub ?

Or are you thinking a more deeper hiding of the pages? henryiii (Henry Schreiner) June 21, 2022, 10:30pm 5 Yes, just that. I’d like to avoid them cluttering the side bar, but they are fine sitting in the repo at the same place, and even being linked to from somewhere not as distracting, including at the bottom of the guides page. An archived or obsolete section in the ToC wouldn’t be terrible either, since they are unexpanded by default.

If everyone is on board and that list looks like the correct start, exact details of the hiding probably could be worked out in a PR. dustin (Dustin Ingram) June 21, 2022, 11:00pm 6 I’m +1 on hiding this guide. pradyunsg (Pradyun Gedam) June 21, 2022, 11:07pm 7 Yes please! This has been on my bucket list for about an year now – but I distracted myself with GitHub - pradyunsg/lutra: Ooops, I wrote another Sphinx theme! [very WIP, do not use] instead.

Remove them from whichever .. toctree references the document, and put a :orphan: on the top of the document. This way, Sphinx will still generate the HTML for that page, but it won’t be linked to from any of the relevant site structure thingies. 4 Likes henryiii (Henry Schreiner) June 22, 2022, 2:58am 8 Tried it here, seems to work! chore: remove obsolete pages from the ToC by henryiii · Pull Request #1094 · pypa/packaging.python.org · GitHub So for using-manifest-in , should that keep the same name/URL, and just become a small intro to ways to control the contents of the SDist (maybe with examples of how to look inside an SDist), and links to docs on setuptools, hatch, etc. on source inclusion?

Maybe with an example for setuptools and hatch, something like that? (And if we ever standardize a [source] section, that would go here? ) CAM-Gerlach (C.A.M. Gerlach) June 22, 2022, 7:50am 9 Thanks @henryiii ! I’d been thinking much the same (especially after our big reorganization of the dev guide that promises to dramatically improve usability and navigation) but like @pradyunsg it was on that long list of things I want to help but haven’t found the time for, heh…which seems to get inexorably longer as the days go by, such that if something is far enough down the list, like far-away galaxies amidst cosmic inflation, it will likely never happen.

Speaking of which, maybe its time to upgrade the PyPUG site to a modern theme like Furo ? Beat me to it . Assuming you or someone has time to update it, those content updates seem reasonable. Instead of keeping it at a legacy URL, you could use sphinx-reredirects , sphinx-rediraffe or similar, and/or host/CDN-level redirects, to redirect the old URL (and page name in the source) to something more appropriate, like controlling-package-contents or something like that. rouilj (John P.

Rouillard) June 27, 2022, 5:02pm 10 Are there other resources for migrating a codebase from python2 to 3 or making a multilingual code base? If not I would suggest keeping Supporting multiple versions as a reference for people working on multilingual code bases. Having a document to point to that describes tips and techniques to maintain multilingual apps and libraries is useful. henryiii (Henry Schreiner) June 27, 2022, 6:47pm 11 First step is done, the four mentioned pages are no longer in the menus, simplifying the discovery of the remaining more useful pages.

Pretty sure that’s why Lutra is being created. There was an attempt to go to Furo (which would be great, IMO), but it’s on hold since Lutra is supposed to be a better fit (which would also be great). Minor aside: I’m not fond of top bar + side bar navigation (like Hatch uses) when it’s hard to discover. I never realize that the top bar has links that are not in the side bar. Maybe a personal thing, but I kept finding stuff in Hatch that I couldn’t navigate to, and finally realized it was due to the top bar.

Lutra looks like it has that. I don’t know how to visually fix it - maybe if the side bar was blank on the home page, forcing discovery of the top bar? I think this is why I found NumPy’s implementation of the split navigation much easier to discover than Hatch’s. The one that was here was not very good. It was very dated, covering Travis CI (running Ubuntu 12.04!), and was almost completely made up of a few links and a recommendation for python-future & six - the whole thing was under two pages long.

I don’t think this would help in migrating 2->3 mu

The rest of this page is on the live site.