DunderLab’s Documentation Guide¶
This Python module facilitates the creation of Sphinx Documentation directly from Jupyter Notebooks. Essentially, it provides a preconfigured environment that utilizes nbsphinx in the background, complete with custom styles and preloaded modules.
Installation¶
$ pip install -U dunderlab-docs
To generate Sphinx
documentation, start with
the
sphinx-quickstart
command. Then, in the Sphinx conf.py
file, add
‘sphinx’
and dunderlab.docs
to the extensions list.
extensions = [
'nbsphinx',
'dunderlab.docs',
]
Configuration¶
dunderlab_custom_index
¶
This setting allows you to insert a custom ReStructuredText into the
index.rst
file. This custom index will be rendered following the
main index and will also appear in the sidebar.
dunderlab_custom_index = f"""
.. toctree::
:glob:
:maxdepth: 2
:name: mastertoc3
:caption: Submodule 1
notebooks/submodule1/*
.. toctree::
:glob:
:maxdepth: 2
:name: mastertoc3
:caption: Submodule 2
notebooks/submodule2/*
"""
dunderlab_color_links
¶
Customize your documentation’s appearance by altering the link colors.
For instance, setting dunderlab_color_links
to #4db6ac
changes
all links to a blue shade, adding a unique touch to your documentation.
Remember, changes to the stylesheet impact the entire documentation, so
test thoroughly before publishing.
dunderlab_color_links = '#4db6ac'
dunderlab_code_reference
¶
This configuration value can be used to disable the generation of
certain index inputs in Sphinx documentation. Specifically, setting to
True
will enable the generation of the index inputs genindex,
modindex, and search, while setting it to False
will disable their
generation.
dunderlab_code_reference = False
dunderlab_github_repository
¶
This configuration specifies the project repository, which will be used
to adjust the URLs of the images in the README.md
file.
Notebooks¶
In the first build, for example make clean html
, the system will
create (if not yet exist) the folder notebooks
with some files in
it.
docs/
build/
source/
conf.py
index.rst
_modules/
_static/
_templates/
-> notebooks/
-> 01-getting_started.ipynb
-> readme.ipynb
-> __sandbox.ipynb
The readme.ipynb
notebook is mandatory, as it generates the
README.md
file in the root of the Python package. Documentation
notebooks should be named with numeric prefixes for sorting purposes.
Notebooks named with __
prefixes won’t be rendered into the
documentation.
Special Notebooks names¶
readme.ipynb
¶
This notebook is used to generate the main documentation page, which is
typically the index.rst file
. The notebook is converted into a
ReStructuredText file, which is then rendered as HTML to create the main
documentation page. Additionally, the readme.ipynb
notebook is also
used to generate the README.md
file that is typically found in the
root of your project. This file can provide a brief overview of your
project and its purpose, along with any relevant installation or usage
instructions.
license.ipynb
¶
This notebook is used to generate the LICENSE
file that is typically
found in the root of your project. This file specifies the terms under
which your code is licensed and provides information about how others
can use and modify your code. It is recommended that the
license.ipynb
notebook contain a single Markdown or plain text cell
that includes the full text of your project’s license. This can help
ensure that the license text is accurate and up-to-date, and can
simplify the process of updating the license if needed.
Features¶
Automatic generation of README.md
Automatic index in html view
Compatibe with Read the Docs
Troubleshooting¶
conf.py
fileimport os
import sys
sys.path.insert(0, os.path.abspath('relative_path_to_module'))
README.md
file’s location.readme.ipynb
notebook should be placed in a
folder called _images
.