No project description provided
Project description
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.
footer.ipynb
This notebook is used to generate a footer that appears at the bottom of the main documentation page and the project's README.md
file. It can contain any content you want to include in the footer, such as copyright information, acknowledgments, or links to related resources. During the documentation build process, the notebook is converted into HTML and added to the bottom of the main documentation page and README.md
file.
Features
- Automatic generation of README.md
- Automatic index in html view
- Compatibe with Read the Docs
Troubleshooting
If the Index and Module Index appear empty:
Resolve this by adding the target module's path to the PATH variable in the conf.py
file
import os
import sys
sys.path.insert(0, os.path.abspath('relative_path_to_module'))
If images aren't visible in the readmereadme.md file:
Verify their paths to ensure they're accessible from the GitHub repository. Relative paths must be correctly set relative to the README.md
file's location.
The images used in the readme.ipynb
notebook should be placed in a folder called _images
.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for dunderlab_docs-1.19-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 273176daf6e427ee23788bb7a8abdf5a07522cd6dc9263d4a0baab227ce7a2f3 |
|
MD5 | 0ef3a20bff99361c829231279f206ac6 |
|
BLAKE2b-256 | 79a7de2c0f284d0b7f6b537c445f49e3ec1f11d697e3d076ae605d86d0f3c08c |