Cleaning up guides

Currently there are a lot of guides on 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:

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.

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?


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 so that the links to these documents are under a heading “obsolete”, and/or the link texts to each get some indicator of “obsolete”.


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. :slight_smile:

As in the Table of Contents like at main · pypa/ · GitHub ? Or are you thinking a more deeper hiding of the pages?

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.

I’m +1 on hiding this guide.

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. :sweat_smile:

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. :slight_smile:


Tried it here, seems to work! chore: remove obsolete pages from the ToC by henryiii · Pull Request #1094 · pypa/ · 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? :slight_smile: )

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 :smiley: ?

Beat me to it :smile: .

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.

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.

First step is done, the four mentioned pages are no longer in the menus, simplifying the discovery of the remaining more useful pages. :slight_smile:

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 much, or in multilingual (guessing you mean 2+3) codebases. At this point, I’d assume someone maintaining a codebase already has 2+3 implemented, and people should not be adding new 2+3 code bases. New code shouldn’t be using six & python-future. From what I can tell, python-future has a nearly two year old open PR adding Python 3.9 (!) support.

There are lots of good blog posts and talks from years ago discussing migrating 2->3 or maintaining 2+3 codebases that are easy to search for. Maintaining 2+3 is not recommended anymore; recent versions of Python are actively removing Python 2 compatibility holdovers. So don’t think it should be menu item. (Also, the page is still there as you linked to it, it’s just not discoverable via the menu anymore.)


John, what do you mean by “multilingual code base”? Do you mean, “supports Python 3.x and 2.x”? Or, “written in a mixture of Python and Rust”? Or do you mean, “written in pure Python 3.x, but displays UI in both French and Urdu”?

When I hear “multilingual”, my mind jumps immediately to the third meaning.


Yes, that is indeed the primary motivator. :slight_smile:

I meant is runnable under (versions of) Python 2.x or 3.x. Do you have a better term for that distinction? Multiversionally doesn’t exactly roll off the tongue 8-).

i18n or internationalized application is what I think of when talking human languages (option 3).

Isn’t option 2 (mix of python and rust) just called an abomination 8-)?? Actually, can #2 be done using a bindings mechanism similar to C and C++?

Thank you for the clarification. Sorry, “supports Python 3.x and 2.x” is the best phrase I have. To my mind, a code base like that supports only one language, Python.

Ah! It turns out that this is my particular discipline. We have so many different terms for closely related concepts. A “multilingual” application interacts with the user in multiple human languages, usually one language at a time. “Localisation” is the process of adding to an application the UI text and functionality adjustments so that it can interact with the user in an additional human language. “Internationalisation” is the process of adding functionality to an app which makes the localisation task faster, easier, and cheaper. Example: “The costs of internationalisation pay off in reduced overall costs of localisation when making a multilingual app.”

And there are more terms beyond those.

But that isn’t really a packaging concern as that will come down to whether the packaging tools you choose to use support running under Python 2/3.

My impression from speaking with @pradyunsg was that

Lutra was targeting larger and more complex docs sites than Furo; the PyPUG doesn’t really have that many more pages than the devguide, which uses Furo, or the Furo demo site. But I’d defer to @pradyunsg as to the benefits of Lutra for this case.


FWIW, the three-layer layout is rather confusing to me as well.

As far as I’m aware it previewing and reviewing it, it just has two sidebars, just like Furo, as well as Pydata-Sphinx-Theme (which we/Spyder use our own custom variant of). Could you point to a page where you see this?

I thought that major motivation behind Lutra was for bigger and more complex doc sites, whereas the PyPUG (especially with these changes) really isn’t much bigger than the devguide, which uses Furo?

When actually termed something, what I usually hear is a [Py2-Py3] “hybrid” codebase. However, after this became the near-universal standard for Py3 porting, followed by dropping Py2, there wasn’t so much of a need to give it an explicit name, as opposed to more usefully talking about what Python versions the codebase supports.

No, it’s called maturin :slight_smile: And its pretty cool, actually.

And nowadays, modern versions of most if not all of them don’t, AFAIK.

On next release I enabled sticky tabs


That should help. BTW, @ofek, I suggest you add a dedicated Docs link to the hatch section in Project Summaries, like most of the other listings. A link to the Github repo isn’t very user-friendly…