Skip to content

Install sphinx-notfound-page by default for nice 404 pages #7870

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
4 tasks
humitos opened this issue Jan 26, 2021 · 3 comments
Closed
4 tasks

Install sphinx-notfound-page by default for nice 404 pages #7870

humitos opened this issue Jan 26, 2021 · 3 comments
Labels
Feature New feature Needed: design decision A core team decision is required

Comments

@humitos
Copy link
Member

humitos commented Jan 26, 2021

We have built an amazing feature on Read the Docs to be able to serve custom 404 pages for projects together with a Sphinx extension that automatically builds a nice 404 page without any effort and almost not configuration.

However, people have to install it by themselves on their projects and configure it.

Benefits

  1. all 404 pages will be nice and link to all the other sections of the project
  2. no more Maze Found page with no reference to the original documentation project we are browsing
  3. reduce amount of checks in our 404 handler (404.html will always exists and be served immediately)

Downsides

  1. we are adding another external dependency that we need to maintain over time (see Docs: policy for supported tools and dependencies #7859)
  2. would this override an existent custom 404.html file?
  3. disparity between Sphinx and MkDocs features by default

Work required

  • install the pip package
  • configure the extension in our custom conf.py if not installed by user already
  • QA there are no incompatibilities
  • add it under a feature flag as initial test
@humitos humitos added Feature New feature Needed: design decision A core team decision is required labels Jan 26, 2021
@stsewd
Copy link
Member

stsewd commented Jan 26, 2021

I think we should stop installing things that aren't needed for building docs, users should explicitly use those tools. This is the same discussion we had about installing the search extension. More adequate would be to write guides on how to integrate/use these tools.

@stsewd
Copy link
Member

stsewd commented Jul 1, 2021

I think we can close this since we are investing more time on the new builders that don't install anything instead?

@humitos
Copy link
Member Author

humitos commented Jul 2, 2021

Yeah. We should write a guide with the "Read the Docs recommended way" or even in the "Getting started with" to mention the extensions we recommend.

Also, we could create a cookiecutter template with our recommended settings.

@humitos humitos closed this as completed Jul 2, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Feature New feature Needed: design decision A core team decision is required
Projects
None yet
Development

No branches or pull requests

2 participants