Documentation

The libraries necessary for building the documentation of each subpackage can be installed through the docs option. For instance, with bsb-core:

pip install bsb-core[docs]

You should have these libraries already if you have installed the bsb with nx, with the editable-install.txt script, or with the dev flag. You can build the documentations for each package with the following command (here shown for bsb-core):

./nx run bsb-core:docs

cd packages/bsb-core/docs
make html

The output will be inside the subpackages folder, under the /docs/_build folder.

Note

Note that the command make html by default does not show you warnings in the documentations. These warnings will not pass the tests on the Github repository. To test if the documentations was properly implemented, prefer the command:

sphinx-build -nW -b html . _build/html

Conventions

Except for the files located at the root of the project (e.g.: README.md), the documentation is written in reStructuredText . Docstrings in the python code should therefore be in the reStructuredText (reST) format.
In the documentation, the following rules should be implemented:

  • Values are marked as 5 or "hello" using double backticks (`` ``).

  • Configuration attributes are marked as attribute using the guilabel directive (:guilabel:`attribute`)

  • Use short-circuited cross-references: prefix the target with ~ so only the final component is shown, e.g. :class:`~bsb.config.BuildContext` renders as BuildContext instead of the full dotted path. Omit the ~ only when the surrounding sentence genuinely needs the full path.

  • No em dashes, and no en dashes outside numeric ranges. Use a colon, period, comma, or parentheses, or rewrite the sentence. This includes --- typed in flowing prose, which Sphinx auto-converts to an em dash.

  • Do not reference development history in committed text. Avoid issue numbers, “introduced for X”, “as part of the Y migration”, and similar phrasing in docs, docstrings, and comments. The one exception is a regression-test docstring that names the bug it guards against.

  • Write “the BSB”, not “BSB”, in flowing prose. As an initialism it takes the definite article.