Instructions: General Documentation#
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
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
source/content folder of the
brightway-documentation repository. The homepage is located in
source/conf.py file contains the configuration for the documentation build.
. ├── environment.yml ├── source/ │ ├── conf.py | ├── index.md │ └── content/ │ ├── setup/ │ ├── introduction/ │ └── (...other documentation sections) ├── README.md ├── brightway2-io/ ├── brightway2-data/ └── (...other Brightway modules)
Markdown (and reStructuredText)#
The the different pages of the Brightway documentation are 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 ReStructured Text (
rst) directives in Markdown files. The
sphinx-design package is used for advanced layout and interactive element support.
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