canonical / sphinx-docs-starter-pack

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

add a custom 404 page #55

Closed ru-fu closed 1 year ago

ru-fu commented 1 year ago

Fixes #51.

Unfortunately, the page doesn't display right in the preview (because that uses a different URL structure than the real docs). I tested the paths though, and I'm positive they are correct. :)

ru-fu commented 1 year ago

It's possible to specify the page not found text within conf.py - it might be better to do that rather than having an orphan page, simply for ease of configuration (i.e., having all that config in as few places as possible)

I felt that blows up the config file, and it's easier to find how to modify the 404 page when having it explicitly as a page.

Maybe the question is whether we want every project to use the same text - then putting it in the conf.py file shoud be okay. But if we want to allow customising it, I find a separate file easier to maintain.

pmatulis commented 1 year ago

The first question to answer is whether we consider the 404 page a customisable element or not. I don't think it should be and having a separate page would make it tempting for projects to edit it. So my opinion is to hardcode it in conf.py. One customisable aspect could be if the 404 config sourced some image that is a customisable object (in custom_conf.py).

If others do think the 404 page should be customisable, to be 100% consistent with our current approach, we would embed the 404 page in conf.py and then allow for an override in custom_conf.py . So again, no separate page.

ru-fu commented 1 year ago

Thanks! I don't have any strong opinions, so updated. For now without an option to override the text, but that should be easy to add if we need it.