Jupyter book#
This webpage is built using Jupyter book, which is a tool to generate webpages from markdown, restructured text,python notebooks and many other formats.
A Jupyter book can consist of a combination of these kinds of files, and can allow users to interact with the code and visualize the results. Examples can be found at:
There are two files that are required to build a Jupyter book, the Table of Contents and the Configuration-file.
A good guide for setting up the book can be found at: Jupyterbook - Official documentation
Installation and building#
Jupyter-book can be installed with pip
python -m pip install jupyter-book
and building the book can be done with the following command
jupyter-book build path/to/_config.yml
_toc.yml#
A yaml file listing the contents of the book. See: Jupyterbook - Table of Contents for more information.
_config.yml#
A configuration file for the book, see: Jupyterbook - Configuration reference for the full list of options.
Publishing book#
The book can be published following Publishing to Pages, where
step 3 in the official action would be calling jupyter book build . to generate the documentation at _build/html, which in turn is the folder we upload as a Github page.
A Github action showing some of the steps can be found at Actions/deploy-pages.
Automatic building of Package API#
For packages, one can use the auto-doc-extension of Sphinx to automatically generate an API for the Python package. See: Jupyterbook - Package API for more information.
An example of the automatically generated API can be found at https://scientificcomputing.github.io/example-python-package/docs/api.html