Contribution Guide: General Documentation#
Details on the concept and technical implementation of the new Brightway documentation are detailed in Brightway Enhancement Proposal (BEP) 003.
The Brightway documentation is built with Sphinx, the Python documentation generator. It is hosted on Read the Docs. All relevant code resides in the
Markdown (and reStructuredText)#
The majority of the Brightway documentation is based on Markdown (
.md) files. The MyST package is used to enable Markdown support across the project. The
eval-rst function in MyST allows for use of arbitrary
rst directives in Markdown files. The
sphinx-design package is used for advanced layout and interactive element support. Wherever necessary, reStructuredText (
.rst) files or directives can also be used.
myst-nb package is being used to render Jupyter Notebooks in the documentation. This allows for the use of Jupyter Notebooks as a documentation format. The notebooks are stored in the
notebooks folder in the
brightway-documentation repository. Curtrently, the notebooks are not executed during the build process. Any markdown cell in a notebook supports the features of the
myst-parser, including admonitions,
eval-rst directives, and
Building the Documentation#
The Brightway documentation is built and published automatically by the readthedocs.org service on every push/merge to the
main branch of the
brightway-documentation repository. To preview your changes, build the documentation locally by following the instructions in the repository readme.
Technical Setup Information#
The content of the Brightway documentation is stored in the
sphinx/source folder of the
brightway-documentation repository. The homepage is located in
sphinx/source/conf.py file contains the configuration for the documentation build.
. ├── setup/ │ └── conda_environment.yml ├── sphinx/ │ └── source/ │ ├── conf.py │ ├── index.md │ ├── setup/ │ ├── introduction/ │ └── (...other documentation sections) ├── README.md ├── brightway2-io/ ├── brightway2-data/ └── (...other brightway2 modules)