The primary documentation for the Brightway life-cycle assessment software package. Sphinx and readthedocs.org are used to build/host the documentation.

Brightway modules are split up into different repositories (brightway-2-analyzer, brightway2-calc, etc.). These repositories are included as git submodules in this repository in order to e.g. enable Sphinx to build a combined changelog page.

All content pages of the documentation are Markdown formatted for reasons of simplicity. The API documentation is build from source automatically by the readthedocs.org Sphinx extension AutoAPI.

1. Clone this repository:

git clone https://github.com/brightway-lca/brightway-documentation.git

2. Initialize (=download) the submodules (brightway-2-analyzer, brightway2-calc, etc.):

git submodule update --init --recursive --remote --force

Note that if the --remote flag is not set, the submodules will point to the latest commit on the default branches (main), not to the latest commit on the branches specified in the .gitmodules file. On the main branch of the brightway-documentation repo, all submodule branches specified in the .gitmodules should be main. This is to ensure the documentation is always up-to-date with the latest changes in the submodules.

To manually update the submodules, use the same command again. There is no need to push changes to the submodules to the remote, since they are updated by GitHub Actions.

Set up a Python virtual environment that includes all packages required to build the documentation. A Conda environment file is provided for convenient setup. The file is located at ./environment.yml. Install the environment sphinx by running from the repository root directory:

conda env create -f 'environment.yml'

and activate the environment:

conda activate sphinx

You are now ready to build the documentation...

1. You can build the documentation by triggering every build manually: To trigger the build, run sphinx-build from the repository root directory:

sphinx-build source _build/html -b singlehtml -a

You can now preview the documentation, built as a single html page at:

_build/html/homepage.html

2. You can also build the documentation by automatically triggering a build after every change to the source files, providing a "live" preview of changes. To trigger the automated builds, run sphinx-autobuild from the repository root directory:

sphinx-autobuild source _build/html -a -j auto --open-browser

You can now preview the documentation at (the browser window will open automatically ✨): http://127.0.0.1:8000/

The documentation contains links to external websites. To check if these links are still valid, run the following command from the repository root directory:

sphinx-build -b linkcheck -D linkcheck_workers=20 source _build/linkcheck

Internal links, if formatted according to the myst-parser cross-referencing specifications, are checked automatically during the regular build process.

Please follow the extensive guide we have provided on the documentation website.

Compare the sphinx:

1. documentation
2. getting started (from readthedocs)
3. issues on GitHub

Compare the readthedocs.org:

1. documentation
2. tutorial
3. issues on GitHub