search

canonical / sphinx-docs-starter-pack

A documentation starter-pack
https://canonical-starter-pack.readthedocs-hosted.com/
Other
13 stars 35 forks source link

docs: add remark about Read the Docs redirects #179

Closed dviererbe closed 7 months ago

dviererbe commented 7 months ago

Redirects can be configured with the ReadTheDocs admin dashboard. No project side redirects required.

See https://docs.readthedocs.io/en/stable/guides/redirects.html

dviererbe commented 7 months ago

The extension is optional, so you can already choose to not use it. Removing the extension would be a regression though, because:

  1. Redirects are usually related to PRs - if you delete or rename a file, you should add a redirect for the old file at the same time. With the extension, this is possible. Maintaining the redirects separately in a different tool requires manual work after a PR is merged, and will be forgotten most of the time. Also, you will not store information on why/when a specific redirect was created.

  2. Redirects in RTD work only on RTD, not in local copies (if the docs are shipped with the product, for example).

  3. Without the extension, community contributors cannot create redirects (since they won't have access to the RTD dashboard).

Praise: That makes a lot of sense, thanks for the context!

Note: I changed the scope of the PR to just adding a remark. I would also change the name of the branch, but that would close the PR.