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

QuantEcon / sphinxcontrib-jupyter

A Sphinx Extension for Generating Jupyter Notebooks

BSD 3-Clause "New" or "Revised" License

74 stars 23 forks source link

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

Open mmcky opened 4 years ago

mmcky commented 4 years ago

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 commented 4 years ago

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

mmcky commented 4 years ago

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 commented 4 years ago

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

DrDrij commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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.