Instructions: General Documentation#

Building the Documentation#

The Brightway documentation is built and published automatically by the 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#

Repository Structure#

The content of the Brightway documentation is stored in the source/content folder of the brightway-documentation repository. The homepage is located in source/content/ The source/ file contains the configuration for the documentation build.

β”œβ”€β”€ environment.yml
β”œβ”€β”€ source/
β”‚   β”œβ”€β”€
|   β”œβ”€β”€
β”‚   └── content/
β”‚       β”œβ”€β”€ setup/
β”‚       β”œβ”€β”€ introduction/
β”‚       └── (...other documentation sections)
β”œβ”€β”€ brightway2-io/
β”œβ”€β”€ brightway2-data/
└── (...other Brightway modules)

Document Syntax#

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.

Jupyter Notebooks#

The 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 myst directives.