|
|
This document will guide you through on how to update a Bob package to be properly built with Sphinx 3 (when upgrading from Sphinx 2).
|
|
|
It is also useful for helping you fix Sphinx warnings
|
|
|
|
|
|
# Build the documentation
|
|
|
To build the documentation of a package (e.g. `bob.extension`), you can follow the steps below:
|
|
|
```sh
|
|
|
# install bob.devtools
|
|
|
$ conda create -n bdt -c https://www.idiap.ch/software/bob/conda/label/beta -c https://www.idiap.ch/software/bob/conda bob.devtools
|
|
|
$ git clone git@gitlab.idiap.ch:bob/bob.extension
|
|
|
$ cd bob.extension
|
|
|
$ bdt create -vv --python=3.6 bob_extension
|
|
|
$ conda activate bob_extension
|
|
|
$ buildout
|
|
|
$ export BOB_DOCUMENTATION_SERVER="https://www.idiap.ch/software/bob/docs/bob/%(name)s/master/"
|
|
|
$ bin/sphinx-build -aEW doc sphinx
|
|
|
$ bin/sphinx-build -aEb doctest doc sphinx
|
|
|
```
|
|
|
|
|
|
# Port the autodoc options
|
|
|
All Bob packages need a similar change as done in https://gitlab.idiap.ch/bob/bob.extension/-/merge_requests/120
|
|
|
As explained in https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options
|
|
|
|
|
|
You may use the script `bdt sphinx migrate-autodoc-flags` added in https://gitlab.idiap.ch/bob/bob.devtools/-/merge_requests/188
|
|
|
to automatically do this change. It works for 90% of Bob packages. Your changes should match the changes in https://gitlab.idiap.ch/bob/bob.extension/-/merge_requests/120
|
|
|
|
|
|
# Fix the C documentations.
|
|
|
Sphinx 3 has change the directives for the C language a lot, see:
|
|
|
https://github.com/sphinx-doc/sphinx/issues/7457
|
|
|
|
|
|
For example these changes: https://gitlab.idiap.ch/bob/bob.extension/-/merge_requests/118/diffs#ba1b201012288ce30c7c3989c742c4187a8ba857
|
|
|
were necessary for bob.extension after I realized this in https://github.com/sphinx-doc/sphinx/issues/8379#issuecomment-722607752
|
|
|
|
|
|
# Automatically generate Python docstrings
|
|
|
It is often useful to automatically generate docstrings for your Python code
|
|
|
to limit the warnings that you might get.
|
|
|
There are many auto doc generation plugins out there but from my personal experience AutoDocstring
|
|
|
from sublimetext is superior to all of them. Give it a try:
|
|
|
|
|
|
* Install https://www.sublimetext.com/
|
|
|
* Open Sublime Text and install Package Control https://packagecontrol.io/installation
|
|
|
* Install `AutoDocstring` https://packagecontrol.io/packages/AutoDocstring
|
|
|
* Change AutoDocstring's `style` to `numpy` in its settings: https://github.com/KristoforMaynard/SublimeAutoDocstring#settings
|
|
|
* Use its keyboard shortcut to automatically update/generate docstrings: https://github.com/KristoforMaynard/SublimeAutoDocstring#usage
|
|
|
* Fill out the rest of the generated docs.
|
|
|
|
|
|
# Disable warnings being treated as errors (Highly discouraged)
|
|
|
As a last measure, **especially after you fix the autodoc options**, you may disable the option that tell Sphinx to treat warnings as errors.
|
|
|
To do so, you would change the `conda/meta.yaml` file of your Bob package and change this line:
|
|
|
```yaml
|
|
|
- sphinx-build -aEW {{ project_dir }}/doc {{ project_dir }}/sphinx
|
|
|
```
|
|
|
to:
|
|
|
```yaml
|
|
|
- sphinx-build -aE {{ project_dir }}/doc {{ project_dir }}/sphinx
|
|
|
```
|
|
|
basically removing the `-W` flag from sphinx builds. |
|
|
\ No newline at end of file |