Brightway Documentation (Sphinx/readthedocs.org)

✨ The Brightway Documentation page is a PyData Sphinx featured site (since 01.2024) ✨

Maintainance Team : @michaelweinold, @cmutel, @tngTUDOR

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

static documentation	interactive documentation	development playground
docs.brightway.dev	learn.brightway.dev	live.brightway.dev

Overview

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/index.md. The source/conf.py file contains the configuration for the documentation build.

Brightway modules are split up into different repositories for strategic reasons (brightway-2-analyzer, brightway2-calc, etc.). These repositories are included as git submodules in this repository. This allows the Sphinx documentation generator to easily to build a combined changelog page or generate an API documentation from Brightway source code.

.
├── environment.yml
├── source/
│   ├── conf.py
|   ├── index.md
│   └── content/
│       ├── setup/
│       ├── introduction/
│       └── (...other documentation sections)
├── README.md
├── brightway2-io/ (git submodule)
├── brightway2-data/ (git submodule)
└── (...other Brightway modules as git submodules)

Sphinx

The Brightway documentation is built with Sphinx, the Python documentation generator. All relevant code resides in the brightway-documentation repository.

readthedocs.org

The documentation is hosted on readthedocs.org. The build is triggered automatically every time the main branch of the brightway-documentation repository is updated. The build process is currently .

Three users are currently assigned as administrators: @cmutel, @michaelweinold and @tngTUDOR.

git submodules

The core functionality of Brightway is provided by different packages (e.g. brightway-calc, brightway-data). For strategic reasons, these packages are maintained as separate repositories. The content of these repositories is included in the brightway-documentation repository through git submodules. This enables sphinx to include files from these repositories in the documentation directly (e.g. README.md). It further enables sphinx-autodoc both locally and in the readthedocs.org service to build the API documentation from source instead of importing all Brightway packages during the build process.

Quickstart

Setup Repository

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

option	description
init	initializes (=downloads) submodules if not currently present
recursive	goes through all submodules specified in the .gitmodules file
remote	points to the latest commit on the branches specified in the .gitmodules file
force	ensures that accidental edits in the submodules are always overwritten

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.

Setup Python Environment

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...

Building 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 --builder=singlehtml --jobs=auto --write-all; open _build/html/index.html

option	value	description
sourcedir	source	N/A
outdir	_build/html	N/A
--builder	html	default builder
--write-all	N/A	always write all output files
--jobs	auto	speed up build by using multiple processes

Your browser should automatically open. You can also open the build manually, stored 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

positional argument or option	value	description
sourcedir	source	N/A
outdir	_build/html	N/A
-a	N/A	always write all output files
-j	auto	speed up build by using multiple processes
--open-browser	N/A	automatically open browser

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

Contributing

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

Manual

Updating the Build Environment

The build environment (packages and versions used by Sphinx to build the documentation) is defined in the Conda environment file ./environment.yml.

Package versions are "pinned" to ensure that the documentation is always built with the same versions. Otherwise, changes in one of the packages might break the build. Package versions are not updated automatiaclly. In doing so, we are following the recommendation by the community:

[The pydata-sphinx-theme] is still under active development, and we make no promises about the stability of any specific HTML structure, CSS variables, etc. Make these customizations at your own risk, and pin versions if you’re worried about breaking changes!

To update the package versions, edit the file and test the build locally, before pushing the changes to the remote.

Updating Git Submodules

What if you want to update the docstrings of a Brightway package (eg. bw2data) and check if they render correctly in the documentation? You can do this by updating the submodule brightway2-data and building the documentation:

1. Use the git submodule set-url command to update the URL of the submodule:

Note

Replace brightway2-data with the name of the submodule you want to update.
Replace https://github.com/(...)) with the URL of the submodule you want to update.

git submodule set-url brightway2-data https://github.com/michaelweinold/brightway2-data

This will update the URL in the .gitmodules file and in the .git/config file:

[submodule "brightway2-data"]
	path = brightway2-data
	url = https://github.com/michaelweinold/brightway2-data
	branch = main

2. Use the git submodule update command to update the submodule:

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

3. Now build the documentation as described above.
4. To change the URL of the submodule back to the original URL, repeat step 1. with the original URL.

Updating the Example Gallery

Examples are collected in the form of Jupyter Notebooks in the brightway-examples repository. This repository is included as a submodule in this repository at .source/content/examples/brightway-examples.

When new examples are added to the

To update the submodule, follow the steps described in Updating Git Submodules.

Checking for Dead External Links

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

positional argument or option	value	description
-b	linkcheck	linkcheck builder
-D	`linkcheck_workers=20``	number of links to check in paralell
sourcedir	source	N/A
outdir	_build/linkcheck	_build/linkcheck/output.txt contains a list of all broken or redirected links

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

GitHub Actions

The git submodules in the brightway-documentation repo are automatically updated every time the source repositories (eg. brightway2-data) are updated. Since the readthedocs.org build is then triggered, the API documentation is automatically updated every time that new code is added to a Brightway library. This is accomplished by three GitHub Action workflows:

and a GitHub App to ensure the workflows have the necessary permissions to update the submodules. The actions are connected as follows:

  flowchart TD;
    id1([<tt>bw2data</tt> updated])
	--> 
	id2(<tt>bw2data</tt> Action: <a href='https://github.com/brightway-lca/brightway2-data/blob/main/.github/workflows/trigger_submodule_update_reuse.yml'>Re-Use Workflow</a>)
	-->
	id3(<tt>bw2data</tt> Action: <a href='https://github.com/brightway-lca/brightway-documentation/blob/main/.github/workflows/trigger_submodule_update_main.yml'>Trigger 'Update Submodules'</a>) 
	--> 
	id4(<tt>brightway-documentation</tt> Action: <a href='https://github.com/brightway-lca/brightway-documentation/blob/main/.github/workflows/update_submodules.yml'>Update Submodules</a>)
	--> 
	id5([<tt>bw2data</tt> submodule in <tt>brightway-documentation</tt> updated])
	id7(<a href='https://github.com/organizations/brightway-lca/settings/installations/40187447'><tt>Documentation Workflow App</tt></a>)-- permissions to trigger run -->id3

📚 References

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