Get rid of .html in documentation URLs

[redeboer]

Currently, ComPWA repos follow the following convention for files under the Sphinx source tree:

...
docs/dynamics.ipynb          --> .../dynamics.html
docs/dynamics/custom.ipynb   --> .../dynamics/custom.html
docs/dynamics/k-matrix.ipynb --> .../dynamics/k-matrix.html
...

See URL structure for this example here. It would

Note

Updates since #158 (comment): .html can be removed from the URL with Sphinx's dirhtml builder. Read the Docs supports good redirects from page.html to page/, so we can remove the .html there. GitHub Pages already supports leaving out the .html, so we can keep the html builder there.

Read the Docs repositories

Preview Give feedback

1. DOC: remove .html from page URLs qrules#245
   📝 Docs +1
   
2. DOC: remove .html from page URLs ampform#388
   📝 Docs +1
   
3. DOC: remove .html from page URLs tensorwaves#515
   📝 Docs +1
   
4. DOC: remove .html from page URLs PWA-pages#209
   📝 Docs +1
   
5. DOC: remove .html from page URLs redeboer/bossdoc#50
   📝 Docs +1
   

Old solution

To get rid of the .html, you would need a structure like this:

docs/dynamics/index.ipynb          --> .../dynamics
docs/dynamics/custom/index.ipynb   --> .../dynamics/custom
docs/dynamics/k-matrix/index.ipynb --> .../dynamics/k-matrix

Disadvantages:

• Have to create folders for each notebook or Markdown source file
• All notebooks are named index.ipynb
  Advantages:
• Nicer URLs, e.g. compwa-org.rtfd.io/report/001
• Dependencies and file output is contained of notebooks is contained within subfolder

Perhaps there are other solutions, like some plugin that does the hierarchy conversion to index.html in a subfolder automatically?

[redeboer]

Note: Jupyter Book seems to generate the index.html structure by default

[redeboer]

This can now partially be achieved on RTD with redirects:
https://docs.readthedocs.io/en/stable/user-defined-redirects.html#clean-html-urls-redirects
But this still requires a / at the end, for instance compwa-org.rtfd.io/develop/ instead of compwa-org.rtfd.io/develop

[redeboer]

Another option: sphinx-reredirects

[redeboer]

Solution: use dirhtml builder instead of the html builder. The effect can be seen in ComPWA/compwa.github.io#242 (which was reverted by ComPWA/compwa.github.io#243, because dirhtml is not the best for GitHub pages).

Warning

There is no good way yet to redirect the old .html URLs on GitHub pages. Neither sphinx-reredirects nor sphinxext-rediraffe seem to support {source}.html -> {source}/ redirects.