Rewrite logic - can it exist within Sphinx or should it never happen at the Sphinx level?

[kaycebasques]

pigweed.dev has a need for some basic rewrite logic. E.g. docname pw_string/docs should be renamed to pw_string/index. It seems like this type of logic cannot and should not happen at the Sphinx level, whether through an extension or builder or whatever. Is that correct? env-before-read-docs for example says that you should never add docnames not listed in env.found_docs. Just looking for a general yes or no around the question of whether there's any way to safely do docname rewrite logic in Sphinx.

[picnixz]

I would say "no" to be on the safe side. If you want to rename how your files are being served, that's something you should likely do at the server-level but not at the generation level.

One reason is that if you change the docname, then you need to update all related references. Also, since Sphinx runs in two steps, where in the first you build and the second you write, there should be a consistency between these two, namely you should also remember the association. Also, I don't exactly remember but I think the writing phase uses the docnames that were used by the building phase to write things on the disk.

Can you give me an example of why you would want this rewrite logic?

[kaycebasques]

Thank you. I figured it wasn't a good idea. We don't need this approach; we're just exploring all our options and I wanted to make sure this wasn't one of them.

Regarding use cases:

• Permalinks. E.g. a doc lives at //docs/xyz/build/index.rst in our repo but we want to output it at /build/ on the website.
• Preserving inbound links. E.g. some external blog points to /abc/123/ on our site but we moved that page to /xyz/123/.
• Pretty URLs. E.g. rather than /bnm/qwe.html we want to just serve it as /bnm/qwe. Although arguably it should really be output as /bnm/qwe/index.html so that /bnm/qwe redirects to /bnm/qwe/. This is how Eleventy handles it I believe.

The first and last ones we might be able to handle at build-time. Pretty sure the middle one has to be handled server-side.

[picnixz]

Before closing the discussion, I can suggest using a reverse-proxy and a rewrite logic. A simple NodeJS server + express router would suffice also.