Support custom 404 page

[melaniewalsh]

Describe the bug

I know that Jupyter Book will not work predictably with custom Sphinx extensions, but I've been trying to integrate this Sphinx Not Found Page extension into my Jupyter Book so that I can have a custom 404 page. And I think this could be potentially useful for all Jupyter Book users.

Anyway, when I use this extension, I get the following error:

An error happened in rendering the page 404.
Reason: ValueError("'/' does not start with '/Users/melaniewalsh/mybookname'")

@humitos has been helping me debug this issue and usefully identified that there seems to be a problem in sphinx-book-theme in the function find_url_relative_to_root, which is called from generate_nav_html.

So I was wondering if there were any suggestions about how to make the Sphinx Not Found extension work with the Sphinx Book Theme. Thanks!

To Reproduce

1. Add Sphinx Not Found Page extension to _config.yml

sphinx:
  extra_extensions: 
  - notfound.extension  
  config:
    notfound_context:
        body: "<h1>Page not found.</h1>"
    notfound_no_urls_prefix: True

2. Build Jupyter Book
3. See error

An error happened in rendering the page 404.
Reason: ValueError("'/' does not start with '/Users/melaniewalsh/mybookname'")

Expected behavior

Custom 404 page is built that preserves CSS and JavaScript from Sphinx Book Theme

Environment

• Python Version [e.g. 3.7.1]: 3.8
• Package versions or output of jupyter-book --version:
  Jupyter Book: 0.8.2
  MyST-NB: 0.10.1
  Sphinx Book Theme: 0.0.36
  MyST-Parser: 0.12.10
  Jupyter-Cache: 0.4.1
  NbClient: 0.4.0
• Operating System: Mac OS

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[melaniewalsh]

Sorry I just realized that a custom 404 page was previously mentioned by @chrisjsewell #221! The Sphinx Not Found Page extension wouldn't be necessary if a custom 404 page was integrated in a different way

[chrisjsewell]

Oh yeh was going to mention.
I didn't know about this extension though so thanks for pointing it out 😀
Will have at look to see if any of it's implementation should be incorporated here, or we just allow for comparability with it

[humitos]

I'm the author of the sphinx-notfound-extension. Let me know if I can be useful in some way here.

I don't see specific needs in #221 that won't allow people using sphinx-book-theme to use the extension. In fact, in the description of the issue, the linked project using a custom 404 page is using the sphinx-notfound-page 😄

If there is anything needed to be added to the extension to make it compatible with the sphinx-book-theme, I'd be happy to incorporate it.

[chrisjsewell]

thanks @humitos!
Yeh I'm sure we can work out the issue to support this extension and will let you know 😄

[melaniewalsh]

Hey! I just wanted to share that I was finally able to get the sphinx-notfound-extension working and create a custom 404 page in my Jupyter Book.

I needed to add a "url prefix" to my own repository, which I did in the _config.yml file here.

You can see an example of the custom 404 page here.

Thanks for the great extension, @humitos!

[choldgraf]

ah that's very cool! Thanks for sharing your solution!

[choldgraf]

@melaniewalsh - any interest in making a quick post to the jupyter book discussions board that shows off this pattern? Maybe others would find it useful!

Then I think that we could consider this issue closed?

[humitos]

Thanks @melaniewalsh for sharing the solution!

any interest in making a quick post to the jupyter book discussions board that shows off this pattern? Maybe others would find it useful!

Hehe, I was about to suggest adding an entry in the FAQ of the sphinx-notfound-page project at https://sphinx-notfound-page.readthedocs.io/en/latest/faq.html

Either work to me. So, happy to have it documented somewhere.

[melaniewalsh]

@choldgraf Sure, I'd be happy to write a quick post for the Jupyter Book discussion board! Also @humitos I could add an entry to the sphinx-notfound-page FAQ, too.

But yes I think this issue is closed 🎉