Contribution Guide: API Documentation

Details on the concept and technical implementation of the new Brightway documentation are detailed in Brightway Enhancement Proposal (BEP) 003.

Note

The API documentation is compiled from source by sphinx-autoapi. It is hosted on Read the Docs. All relevant code resides in the brightway-documentation repository.

Docstring Guidelines

Note

The use of descriptive docstrings for all Brightway functions, classes and class methods is mandatory. Brightway has adopted the NumPy Docstring Style.

Using the full extend of the NumPy Docstring features, including the Examples, Raises, See Also, Notes, and References sections, is recommended:

Docstring Features

Feature	Required	Comment
short summary	yes	N/A
extended summary	yes	N/A
parameters	yes	must include types
returns	yes	must be Nothing the function does not return anything
raises	yes	N/A
see also	optional	should like to other relevant functions
notes	optional	scientific/mathematical explanation of the life-cycle assessment functionality
references	optional	references for the information used in notes
examples	yes	mandatory for all public functions, classes and class methods

Contributing Tutorial

Note

This tutorial demonstrates how to contribute to the API documentation of the brightway2-io package. All steps are equivalent for other Brightway packages (brightway2-data, brightway2-calc, etc.).

Make and Preview your Changes

1. Clone the brightway-documentation repo.

2. Fork the brightway2-io repo and create a new branch documentation_improvements.

3. Make the desired changes to the docstrings on the branch documentation_improvements in your fork of the brightway2-io repo.

You can now preview your changes:

1. Edit the file .gitmodules in the brightway-documentation repo to reflect your fork of the brightway2-io repo by changing the <username> in the url field:

[submodule "brightway2-io"]
	path = brightway2-io
	url = https://github.com/<username>/brightway2-io
	branch = documentation_improvements

1. Point the brightway2-io submodule to your fork of the brightway2-io repo. Repeat whenever you have made changes to the docstrings in your fork of the brightway2-io repo:

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

3. Follow the instructions in the readme to build the documentation locally. You can now preview your changes.

Note

Git submodules offer a convenient way to include the documentation of other Brightway packages in the Brightway documentation. However, they are not updated automatically. You need to manually update the submodule directories whenever you have made changes to the docstrings in your fork of the brightway2-io repo.

Publish your Changes

1. Open a pull request with your edits against the main brightway2-io repo.

2. As soon as the changes to brightway2-io have been merged into the main branch, the brightway2-io submodule in the brightway-documentation repo will be updated automatically through a GitHub Actions workflow.

3. The Brightway documentation at readthedocs.org will be built automatically. Your changes are now online!

Technical Setup Information

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.

GitHub Actions

To ensure that the git submodules are always up-to-date, both locally and in the readthedocs.org service, GitHub Actions are used. Whenever changes are made to the main branch of a Brightway package (e.g. brightway-calc, brightway-data), a GitHub action workflow triggers another GitHub actions workflow in the brightway-documentation repository. This workflow updates the git submodules and commits the changes to the main branch of the brightway-documentation repository.

package	action
brightway-documentation
brightway2-calc
brightway2-io
brightway2-data
brightway2-analyzer

brightway-documentation

Note

Compare the documentation on StackOverflow.

name: 'Update Submodules'

on:
workflow_dispatch:

jobs:
sync:
    name: 'Update Submodules'
    runs-on: ubuntu-latest

    defaults:
    run:
        shell: bash

    steps:
    - name: Checkout
    uses: actions/checkout@v2
    with:
        token: ${{ secrets.GITHUB_TOKEN }}
        submodules: true

    - name: Update Submodules
    run: |
        git pull --recurse-submodules
        git submodule update --remote --recursive

    - name: Commit Update
    run: |
        git config --global user.name 'GitHub Actions Submodule Updater'
        git config --global user.email 'bot@noreply.github.com'
        git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
        git commit -am "auto updated submodule" && git push || echo "no changes in submodule to commit"

other repos (eg. brightway2-calc)

Note

Compare the documentation on GitHub.

Warning

GHA_WORKFLOW_TRIGGER must be set as an org-wide secret

name: Create Workflow Dispatch

on:
push:
    branches:
    - main  
workflow_dispatch:

jobs:
build:
    runs-on: ubuntu-latest
    steps:
    - name: Trigger Workflow
        uses: actions/github-script@v6
        with:
        github-token: ${{ secrets.GHA_WORKFLOW_TRIGGER }}
        script: |
            github.rest.actions.createWorkflowDispatch({
                owner: 'brightway-lca',
                repo: 'brightway-documentation',
                workflow_id: 'github_action_update_submodules.yml',
                ref: 'main',
            })