Documenting¶
The documentation is built using Sphinx with the Read The Docs theme.
We try to write the documentation at only one place and reuse it as much as possible. For instance, the home page of this documentation (https://orion.readthedocs.io/) is actually pulled from the README.rst and appended with a table of content of the documentation generated automatically. The advantage of having a single source of truth is that it’s vastly easier to find information and keep it up to date.
Updating README.rst¶
When you need to reference a page from the documentation on the README.rst, make sure to always point to the stable channel in readthedocs (https://orion.readthedocs.io/en/stable/).
If you need to add a link to a specific page in the documentation that is not yet on the stable channel, make the link to the latest channel (https://orion.readthedocs.io/en/latest/). During the release process the link will be updated to the stable channel.
Writing examples¶
There is two types of tutorials in Oríon, the visualization tutorials and the code tutorials. The visualization tutorials are meant to be light in computations and should run on readthedocs. If there is a need for heavy computations to generate data for the visualizations, the code used for the heavy computations should be turned into a code tutorial. As an example, see Checkpointing trials which served for the generation of data in Parallel Coordinates.
To create a new visualization example, create a python script in examples/plotting
with the name plot_{i}_{name}.py
where i
is the index of the new
visualization tutorial and name
is its name.
Likewise, for code examples, create a python script in examples/tutorials
with the name code_{i}_{name}.py
.
The database used in visualization examples should always be the pickleddb
found at examples/db.pkl
(which is ../db.pkl
relative to example scripts file locations).
This is because these tutorials are executed sequentially by sphinx-gallery
and the storage does not get reset between the examples. We could reset the
database at beginning of each examples but that would clutter the tutorial and
likely confuse the users. This is why we fix the database throughout all
visualization tutorials.
The execution of the code examples must be done manually with the following command:
tox -e build-doc-data code_{i}_{name}
This will:
Flush the full database
db.pkl
.Create a database for the given example
code_{i}_{name}
.Execute the script.
Merge back all example databases
db.pkl
.Generate plots for each types of plot and in
docs/src/_static/{experiment.name}_{plot_type}.html
.
You can then git commit
the new code_{i}_{name}_db.pkl
,
the new version of db.pkl
, and all new plots in docs/src/_static/
.
If the new example have additional requirements, add them to
docs/scripts/requirements.txt
.
Building documentation¶
To generate the html and man pages of the documentation, run:
tox -e docs
When writing, you can run $ tox -e serve-docs
to host the content of
/docs/build/html
on http://localhost:8000.