If you find bugs, errors, omissions or other things that need improvement, please create an issue or a pull request at https://github.com/spatialaudio/nbsphinx/. Contributions are always welcome!
Make sure that the necessary prerequisites are installed. Then, instead of pip
-installing the latest release from PyPI, you should get the newest development version (a.k.a. "master") with Git:
git clone https://github.com/spatialaudio/nbsphinx.git
cd nbsphinx
python3 -m pip install -e .
... where -e
stands for --editable
.
When installing this way, you can quickly try other Git branches (in this example the branch is called "another-branch"):
git checkout another-branch
If you want to go back to the "master" branch, use:
git checkout master
To get the latest changes from Github, use:
git pull --ff-only
If you make changes to the documentation, you should create the HTML pages locally using Sphinx and check if they look OK.
Initially, you might need to install a few packages that are needed to build the documentation:
python3 -m pip install -r doc/requirements.txt
To (re-)build the HTML files, use:
python3 setup.py build_sphinx
If you want to check the LaTeX output, use:
python3 setup.py build_sphinx -b latex
Again, you'll probably have to use python
instead of python3
. The generated files will be available in the directories build/sphinx/html/
and build/sphinx/latex/
, respectively.
The nbsphinx
documentation is available in over 30 different HTML themes, with each having its own branch ending in -theme
.
To simplify the building and testing of themes, which is especially needed when changing CSS, we provide you with command line tool to build all themes or a user specified subset. The tool is located at theme_comparison.py
and can be run with:
python3 theme_comparison.py
Before doing that, the required dependencies can be obtained with:
python3 theme_comparison.py --requirements
This will create a list of dependencies in theme_comparison/theme_requirements.txt
. The dependencies can then be installed with:
python3 -m pip install -r theme_comparison/theme_requirements.txt
If you just want to build a subset of the themes (e.g. alabaster
and sphinx_rtd_theme
), simply run:
python3 theme_comparison.py alabaster rtd
For more information run:
python3 theme_comparison.py --help
Unfortunately, the currently available automated tests are very limited. Contributions to improve the testing situation are of course also welcome!
The nbsphinx
documentation also serves as a test case. However, the resulting HTML/LaTeX/PDF files have to be inspected manually to check whether they look as expected.
Sphinx's warnings can help spot problems, therefore it is recommended to use the -W
flag to turn Sphinx warnings into errors while testing:
python3 setup.py build_sphinx -W
This flag is also used for continuous integration on Github Actions (see the files .github/workflows/*.yml
) and CircleCI (see the file .circleci/config.yml
).
Sphinx has a linkcheck
builder that can check whether all URLs used in the documentation are still valid. This is also part of the continuous integration setup on CircelCI.