Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/brightway-lca/brightway-documentation
📚🌿 readthedocs.org Sphinx Documentation for Brightway
https://github.com/brightway-lca/brightway-documentation
documentation
Last synced: about 2 months ago
JSON representation
📚🌿 readthedocs.org Sphinx Documentation for Brightway
- Host: GitHub
- URL: https://github.com/brightway-lca/brightway-documentation
- Owner: brightway-lca
- License: bsd-3-clause
- Created: 2022-09-29T05:14:46.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-22T00:15:19.000Z (7 months ago)
- Last Synced: 2024-05-22T16:16:33.727Z (7 months ago)
- Topics: documentation
- Language: Python
- Homepage: https://docs.brightway.dev
- Size: 6.68 MB
- Stars: 4
- Watchers: 8
- Forks: 31
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Brightway Documentation (Sphinx/readthedocs.org)
✨ The Brightway Documentation page is a [PyData Sphinx __featured site__](https://pydata-sphinx-theme.readthedocs.io/en/latest/examples/gallery.html) (since [01.2024](https://github.com/pydata/pydata-sphinx-theme/pull/1580)) ✨
[](https://github.com/brightway-lca)
 [](https://github.com/brightway-lca/brightway-documentation-readthedocs/discussions) \
Maintainance Team : [@michaelweinold](https://github.com/michaelweinold), [@cmutel](https://github.com/cmutel), [@tngTUDOR](https://github.com/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](https://github.com/brightway-lca/brightway-documentation) | [learn.brightway.dev](https://github.com/brightway-lca/brightway-learn) | [live.brightway.dev](https://github.com/brightway-lca/brightway-live) |
## 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`](https://git-scm.com/book/en/v2/Git-Tools-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](https://www.sphinx-doc.org/en/master/), the Python documentation generator. All relevant code resides in the [`brightway-documentation`](https://github.com/brightway-lca/brightway-documentation) repository.
### readthedocs.org
The documentation is hosted on [readthedocs.org](https://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`](https://github.com/cmutel), [`@michaelweinold`](https://github.com/michaelweinold) and [`@tngTUDOR`](https://github.com/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`](https://git-scm.com/book/en/v2/Git-Tools-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:
```bash
git clone https://github.com/brightway-lca/brightway-documentation.git
```
2. Initialize (=download) the submodules (`brightway-2-analyzer`, `brightway2-calc`, etc.):
```bash
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](https://documentation.brightway.dev/en/latest/source/contributing/documentation.html#github-actions).
### Setup Python Environment
Set up a Python virtual environment that includes all packages required to build the documentation. A [Conda environment file](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) is provided [for convenient setup](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file). The file is located at [``./environment.yml``](environment.yml). Install the environment `sphinx` by running from the repository root directory:
```bash
conda env create -f 'environment.yml'
```
and activate the environment:
```bash
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`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html) from the repository root directory:
```bash
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](https://www.sphinx-doc.org/en/master/usage/builders/index.html) |
| `--write-all` | N/A | always write all output files |
| `--jobs` | `auto` | [speed up build by using multiple processes](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-j) |
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`](https://github.com/executablebooks/sphinx-autobuild) from the repository root directory:
```bash
sphinx-autobuild source _build/html -a -j auto --ignore source/content/api* --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](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-j) |
| `--ignore` | `source/content/api*` | ignores API documentation generated with sphinx-autoapi to avoid infinite build loops |
| `--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](https://documentation.brightway.dev/en/latest/source/contributing/contributing.html).
## 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](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#activating-an-environment) [`./environment.yml`](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](https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/index.html#user-guide):
> \[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](https://en.wikipedia.org/wiki/Docstring) 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`](https://git-scm.com/docs/git-submodule#Documentation/git-submodule.txt-set-url--ltpathgtltnewurlgt) 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.
```bash
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`](https://git-scm.com/docs/git-submodule#Documentation/git-submodule.txt-update--init--remote-N--no-fetch--no-recommend-shallow-f--force--checkout--rebase--merge--referenceltrepositorygt--depthltdepthgt--recursive--jobsltngt--no-single-branch--filterltfilterspecgt--ltpathgt82308203) command to update the submodule:
```bash
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`](https://github.com/brightway-lca/brightway-examples) repository. This repository is included as a submodule in this repository at [`.source/content/examples/brightway-examples`](.source/content/examples/brightway-examples).
When new examples are added to the
To update the submodule, follow the steps described in [Updating Git Submodules](#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:
```bash
sphinx-build -b linkcheck -D linkcheck_workers=20 source _build/linkcheck
```
| positional argument or option| value | description |
| ---------------------------- | ----- | ----------- |
| `-b` | `linkcheck` | [`linkcheck` builder](https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder) |
| `-D` | `linkcheck_workers=20`` | [number of links to check in paralell](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-linkcheck_workers) |
| 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](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#cross-references), are checked automatically during the regular build process.
## GitHub Actions
The [`git submodules`](./.gitmodules) 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](https://github.com/features/actions):
[](https://github.com/brightway-lca/brightway-documentation/actions/workflows/update_submodules.yml) \
[](https://github.com/brightway-lca/brightway-documentation/actions/workflows/trigger_submodule_update_main.yml) \
[](https://github.com/brightway-lca/brightway-documentation/actions/workflows/trigger_submodule_update_reuse.yml)
and a [GitHub App](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps) to ensure the workflows have the necessary permissions to update the submodules. The actions are connected as follows:
```mermaid
flowchart TD;
id1([bw2data updated])
-->
id2(bw2data Action: Re-Use Workflow)
-->
id3(bw2data Action: Trigger 'Update Submodules')
-->
id4(brightway-documentation Action: Update Submodules)
-->
id5([bw2data submodule in brightway-documentation updated])
id7(Documentation Workflow App)-- permissions to trigger run -->id3
```
## 📚 References
Compare the `sphinx`:
1. [documentation](https://www.sphinx-doc.org/en/master/)
2. [getting started (from readthedocs)](https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html)
3. [issues on GitHub](https://github.com/sphinx-doc/sphinx/issues)
Compare the `readthedocs.org`:
1. [documentation](https://docs.readthedocs.io/en/stable/index.html)
2. [tutorial](https://docs.readthedocs.io/en/stable/tutorial/)
3. [issues on GitHub](https://github.com/readthedocs/readthedocs.org/issues)