All commit authors signed the Contributor License Agreement.

FYI I have no opinion on this, so I'm dropping my review request.

FYI, just in time for this PR, GitHub (finally) implemented the ability to seamlessly view commit history across file renames and moves.

I do have a concern on scope -- for instance title case / sentence case of headings. I would suggest to merge-as-is (once I've resolved the outstanding points) and do those sort of things as follow-ups.

A

Fixed references, increased max depth, removed spaces from titles, reverted line ending change in developers.csv.

A

I restored the appendix and topic table again to reduce scope of this PR as it seems removing them needs more discussion (Ezio's points).

Partially I want to get this in as it puts this / other PRs in a state of limbo w.r.t. the moves.

A

Also, keep in mind this can't be merged immediately until someone with the appropriate RTD permissions sets up the redirects (or we do them ourselves with my script or sphinx-redirects), and a repo admin can merge the PR (due to the CLA bot bug)— @ezio-melotti are you one here?

Some smallish benefits to having Sphinx-level redirects (either your script, sphinx-redirects, sphinx-reredirects, sphinxext-rediraffe, ...) in addition to more-efficient RTD ones:

• Redirects go live immediately, don't need to sync with setting RTD config
• We get redirects on our forks on RTD (without having to also set up the RTD config)
• We get redirects for local testing
• They're defined in code (although it would a good to put the RTD config under source control for transparency, copying and pasting)

a repo admin can merge the PR (due to the CLA bot bug)— @ezio-melotti are you one here?

Apparently not, as I don't have the option to force-merge, nor access to the repo settings (I requested access in python/steering-council#128).

I definitely agree; having them in the repo and generating them as part of the build process allows testing them locally, is portable between hosts and deployment mechanisms, and makes 100% sure they are in sync with the repo itself (particularly in this case, since otherwise a bunch of inbound links will break), among the other benefits you mentioned.

sphinxext-rediraffe seems really powerful and well suited to this use case, as it can resolve chained redirects while only actually doing a single redirect client-side, can check that deleted/moved pages in the GitHub history are directed, and is an integrated Sphinx extension. Sphinx-reredirect seems to be the other option; its simpler and a bit fresher in terms of maintenance, but doesn't seem to be nearly as sophisticated as rediraffe, especially with its handy features well suited for this use case.

Of course, the RTD config should also be checked in to the repo, especially on one with many contributions/contributors and few admins with limited bandwidth; I've found in general that always checking in infra config and updating them in sync with PRs is far more maintainable than buried in the config of some external service asynchronous from the content changes and that only a few people have access to.

Good news, the CLA bot is fixed! We can do a regular merge when we're ready!

Here's an example of how to have HTML meta redirects without adding a new extension or such, within regular reStructuredText.

https://raw.githubusercontent.com/pypa/pip/main/docs/html/reference/pip_cache.rst

Given that all of the newly introduced "root" documents are basically just toctrees, I think an option worth considering is:

1. Not moving the pages around, and only changing the organisation in the Sphinx toctree directives.
2. Having multiple toctrees with a caption on each, for grouping the various documents -- Furo's own documentation has a toctree with a Development caption: https://raw.githubusercontent.com/pradyunsg/furo/main/docs/index.md

This would bring the navigation closer to something similar to https://tailwindcss.com/docs/.

I haven't looked at the actual code changes, only the rendered documentation, but IMO this approach would also lend toward an easier-to-review PR -- since none of the files would move, none of the pages need updates to their references and the markup changes/cleanups can move into a dedicated follow up. It's also more incremental and likely slower, but it will make reviewing the code changes easier and also result in shorter PRs (which tend to not have as many things slip through the cracks as large reorganisation PRs). :)

Done.

A

Merged, thanks @AA-Turner for the PR and to all the people who reviewed it!