search

readthedocs / sphinx-notfound-page

Create a custom 404 page with absolute URLs hardcoded
https://sphinx-notfound-page.readthedocs.io/
MIT License
48 stars 32 forks source link

Problem with sub-projects #171

Open JamesRandom opened 3 years ago

JamesRandom commented 3 years ago

I have a problem using the extension with sub-projects on readthedocs, and versioned sub-projects in particular.

For example, it partly works with “latest”: https://docs.graphcore.ai/projects/available-memory/en/latest/xyz.html The images and styles are present (because they are picked up from the root project). But the navigation links don’t work (they go to the root project and hence the root 404 page, which is kinda OK but not ideal)

On version branches the images and styles are not found because there is no equivalent version in the root project (e.g. it is linking to /en/1.0.0/_static/css/theme.css) For example: https://docs.graphcore.ai/projects/available-memory/en/1.0.0/xyz.html

So, apparently, I need to set the UL prefix correctly. I tried the following settings:

  1. Setting notfound_urls_prefix = "/" or notfound_urls_prefix = None results in exactly the same behaviour as the default setting, including for "latest" as well as versions.

  2. Always go to the parent project for resources and links

    notfound_urls_prefix = "/en/latest/"

This makes the versions act like “latest”. So the page looks OK, but the links are not correct. For example: https://docs.graphcore.ai/projects/available-memory/en/2.1.0/xyz.html

  1. Always go to the correct project and version for resources and links 
    notfound_urls_prefix = "/projects/available-memory/en/2.2.0/“

In this case, everything works exactly as expected. Page looks correct and the links are correct. For example: https://docs.graphcore.ai/projects/available-memory/en/2.2.0/xyz.html

However, this means that notfound_urls_prefix needs to be set specifically for every project and version. Which is doable (I already have to customise conf.py for each document) but it would be nicer if I didn't have to.

So I wonder if there is a better way?

Versions:

humitos commented 3 years ago

However, this means that notfound_urls_prefix needs to be set specifically for every project and version. Which is doable (I already have to customise conf.py for each document) but it would be nicer if I didn't have to.

This is definitely not great 😄 However, I'm not sure how the sphinx-notfound-page extension could help here. It needs to know the URL path where it will be served to hardcode the links and resources.

There should be a hacky way to solve this with and embed Javascript in the extension, I suppose. It could parse the full URL as {domain}/projects/{alias}/{language}/{version} (e.g. https://docs.graphcore.ai/projects/available-memory/en/2.2.0/xyz.html) and re-write all the links and resources in the DOM --but I doubt that it will always cleanly work 😃

On the other hand, I thought Read the Docs weren't supporting 404 pages on subprojects, actually. See this issue that I opened some time ago there: https://github.com/readthedocs/readthedocs.org/issues/5557

I'm not sure a clean way to solve this problem currently, even if Read the Docs picks the correct 404.html for the subproject 😞 . It seems that what you have found is the best we have for now 💪🏼

JamesRandom commented 3 years ago

Thanks I hadn't seen that issue on Read the Docs.

I can see the problem with the general case. I wonder if would be possible for the sphinx-notfound-page extension to be configured to always go to the 404 page for the root project — that would suit me (all the subproject are set up with identical 404 pages, anyway).