Using jupytext with nbsphinx

Sorry for abusing your issue tracker, this is no bug report but rather an advertisement for my Sphinx extension nbsphinx that allows using Jupyter notebooks as Sphinx source files.

And the reason why I’m mentioning this here, is that I’ve just added a feature (https://github.com/spatialaudio/nbsphinx/pull/234) that allows using jupytext in this process! This should allow using any files supported by jupytext as Sphinx source files.

See https://nbsphinx.readthedocs.io/en/latest/contents-manager.html for documentation.

Note that this feature is currently only available in the master branch, it will be available on PyPI with the next release. It would be great if some people could test it before the next release.

For now, you can install it directly from the Git repository (as described in CONTRIBUTING.rst) or you can use pip like this:

python3 -m pip install git+https://github.com/spatialaudio/nbsphinx.git@master

It would be great if you could try this out and give some feedback if it works and open some issues or pull requests if some things don’t work!

Feel free to close this issue any time.

[jorgepiloto]

Hi all, it’s Jorge from the poliastro dev team. We recently switched our Jupyter notebook based examples to Jupytext and both sphinx-gallery and Binder seem to keep running without any problem.

Migration process was very simple, thank you for this amazing tool. Please refer to migration to Jupyext pull request for more information 😄

[mwouts]

Great news @lukelbd !

Well, could you tell us a bit more? Maybe you have an example that you could share? Especially I’d be curious to know how you structure your documentation - do you maintain the main documentation and the notebooks in two different types of files (.rst and .py maybe?)?

Also, have you seen the new myst format, by the Executable Book Project (cc. @chrisjsewell ) which intends to provide a good rendering of notebooks-like documents with rST content?

Personally I do like very much the idea of testing the documentation. The two examples I have for this are

• test_jupytext_commands_in_the_documentation_work, which tests the jupytext commands in the documentation, once I get tired of getting the documentation wrong…
• The Jupytext/Papermill blog post where I test… the example notebook (Python), and also the blog post itself (using Bash), see the .travis.yml file.

Clearly, instead of testing the doc files, we could also easily lint them with e.g. jupytext --pipe black.

And to conclude, there are two sujects that I’d like to write on when time permits - these are:

• How to write a documentation site, including notebooks #247
• What is a good pre-commit workflow for notebooks #432