FEAT: Incorporate option to have self contained html pages (without server) and readthedocs integration

[mmcky]

A feature that might be useful is to have self contained html pages so they could be opened directly. Currently the make_site is setup to server the html pages via a web server.

[GavinHuttley]

+1 It would be really useful to produce html suitable for readthedocs from just rst!

[mmcky]

Thanks @GavinHuttley in principle the contents of _build/website/jupyter_html should work with readthedocs as it would be hosted. However currently not sure how to change rtd to run a different command to make html and copy the results from a different location.

• [ ] look at potential for readthedocs integration

[mmcky]

@DrDrij what would be invovled in generating html pages that can be opened and styled (without needing a server to be running)?

[DrDrij]

Hmm.

• All internal links need to be relative
• All internal links need to include a full file path and extension (<a href="../getting_started_julia/julia_environment.html">next lecture</a>)
• Links to scripts and stylesheets need to be relative (<link rel="stylesheet" href="../../_static/css/julia.css?v=1.0">)

Easy if all the site pages are at the same level, a lot more challenging if there are nested directories.

[mmcky]

Thanks @DrDrij that is a useful list. So we mainly need a server due to the use of root level referencing to support nested folders.

To implement this the extension would require better management and tracking of paths in the extension for the nested folder case. Something we are looking into for improvements in managing static assets.

[mmcky]

@GavinHuttley this probably won't get looked at in great detail until we undertake the refactor in mid November 2019. Hope that is OK.

[GavinHuttley]

Thanks for asking, I need to release my project earlier than that so will continue with the current mix of rst and ipynb (which currently relies on nbsphinx for integrating of the two types). But I look forward to consolidating on rst so I can take advantage of its capabilities.

I will just make the comment that sphinx includes the pathto jinja2 macro that can be used for establishing relative links (that was in a comment on my junix pull request). The issue I identified was that this project is usingnbconvert for processing the templates, so pathto is not in the namespace.

I wonder how nbsphinx address this?

[mmcky]

thanks @GavinHuttley. We will incorporate more sphinx support in this refactor

https://www.sphinx-doc.org/en/master/_modules/sphinx/environment.html

we will see if we can integrate more closely with pathto information.