No project description provided
Notebook sphinx extensions
This package is available on pypi: https://pypi.python.org/pypi/RunNotebook
Install it using pip:
pip install RunNotebook
Add the extension to your
extensions = [ # Import both 'RunNotebook', # or import each directive individually # 'RunNotebook.notebook_sphinxext', # 'RunNotebook.notebookcell_sphinxext', # ... ]
Optional configuration in your
# Run notebook configuration # The template used when exporting from nbconvert # full - Outputs the full HTML document [Default] # basic - Outputs a single div (with no additional resources) run_notebook_export_template = 'basic' # Default: 'full' # Display the source links to the generated evaluated files run_notebook_display_source_links = False # Default: True
Take a look at the
conf.py file in the example sphinx project to see how to
integrate with your sphinx build.
Code snippets in documentation
This packages two useful Sphinx extensions:
notebook-cell. These extensions are useful for embedding entire
notebooks or single notebook cells, respectively, inside sphinx documentation.
In the past, it was relatively straightforward to include example scripts inside
of version controlled documentation. For example, one could include code
snippets inside of sphinx documentation using the rst
.. code-block:: python for i in range(5): print i
While this does produce a syntax highlighted python script embedded in a sphinx document, it does not run the code or provide any facilities for checking whether the code is correct.
Jupyter notebooks offer a powerful environment for literate programming, with code input, output, and explanatary text embedded into a single document. It's tempting to include notebooks into documentation wholesale. However, there are some issues with this approach as well. Versioning notebooks is difficult - output can change and if the notebook output contains large amounts of data, the diffs can easily grow quickly, producing an inconveniently large repository. In addition, updating the notebook requires manually re-evaluating all the notebook cells, saving the notebook, and making a commit if anything changes. Versioning evluated notebooks also offers no guarantee that the code in the notebook is still functional - a real concern with a notebook documenting an evolving codebase with imperfect test coverage.
Using Sphinx Extensions to Automate Notebook Running
The extensions included in this package make it easy to include unevaluated notebooks or short python code snippets inside of documentation. Both extensions make use of nbconvert to script the evaluation of notebooks and to convert the resulting evaluated notebooks into HTML suitable for embedding in a Sphinx document.
This extension depends on
Suppose I want to include a notebook named
example.ipynb inline in my
documentation. To do so, add the following to any sphinx ReStructuredText
.. notebook:: example.ipynb
During preprocessing, sphinx will evaluate the notebok, convert it to html, and
embed it into the document in the place where the
notebook directive was
If a full notebook does not make sense or if you would like to more tightly link
a script to the source of your documentation, you can use
embed a single-cell mini notebook:
.. notebook-cell:: for i in range(5): print i
This will convert the code snippet into a notebook, evaluate the notebook, and then embed the result in the document. Note that notebook-cell does not currently accept a user namespace, so all imports necessary for the code to run must be included in the source.
example folder in the root of the repository for a full, working
example using a basic sphinx configuration.
These extensions use a version of the 'full' HTML output from the nbconvert HTML output. This includes the full notebook CSS. There's some CSS monkeypatching that happens to reduce the impact of the notebook CSS on the document, which might conflict with your documentation theme. If it turns out that the monkeypatching is fragile and there are visual issues in your preferred docs theme, please let me know by opening a github issue.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size RunNotebook-0.3.1-py2.py3-none-any.whl (7.8 kB)||File type Wheel||Python version py2.py3||Upload date||Hashes View hashes|
|Filename, size RunNotebook-0.3.1.tar.gz (6.7 kB)||File type Source||Python version None||Upload date||Hashes View hashes|
Hashes for RunNotebook-0.3.1-py2.py3-none-any.whl