Contributing to Grain

Contributing to Grain#

Contributing to the Grain project documentation#

Pre-requisites#

To contribute to the documentation, you will need to set your development environment.

You can create a virtual environment or conda environment and install the packages in docs/requirements.txt.

# Create a virtual environment
python3 -m venv .venv
# Activate the virtual environment
source .venv/bin/activate
# Install the requirements
pip install -r docs/requirements.txt

or with conda

# Create a conda environment
conda create -n "grain-docs" python=3.12
# Activate the conda environment
conda activate grain-docs
# Install the requirements
python3 -m pip install -r docs/requirements.txt

Building the documentation locally#

To build the documentation locally, you can run the following command:

# Change to the docs/ directory
cd docs
sphinx-build -b html . _build/html

You can then open the generated HTML files in your browser by opening docs/_build/html/index.html.

Documentation via Jupyter notebooks#

The pygrain documentation includes Jupyter notebooks that are rendered directly into the website via the myst-nb extension. To ease review and diff of notebooks, we keep markdown versions of the content synced via jupytext.

Note you will need to install jupytext to sync the notebooks with markdown files:

# With pip
python3 -m pip install jupytext

# With conda
conda install -c conda-forge jupytext

Adding a new notebook#

We aim to have one notebook per topic or tutorial covered. To add a new notebook to the repository, first move the notebook into the appropriate location in the docs directory:

mv ~/new-tutorial.ipynb docs/tutorials/new_tutorial.ipynb

Next, we use jupytext to mark the notebook for syncing with Markdown:

jupytext --set-formats ipynb,md:myst docs/tutorials/new_tutorial.ipynb

Finally, we can sync the notebook and markdown source:

jupytext --sync docs/tutorials/new_tutorial.ipynb

To ensure that the new notebook is rendered as part of the site, be sure to add references to a toctree declaration somewhere in the source tree, for example in docs/index.md. You will also need to add references in docs/conf.py to specify whether the notebook should be executed, and to specify which file sphinx should use when generating the site.

Editing an existing notebook#

When editing the text of an existing notebook, it is recommended to edit the markdown file only, and then automatically sync using jupytext via the pre-commit framework, which we use to check in GitHub CI that notebooks are properly synced. For example, say you have edited docs/tutorials/new_tutorial.md, then you can do the following:

pip install pre-commit
git add docs/tutorials/new_tutorial.*          # stage the new changes
pre-commit run                       # run pre-commit checks on added files
git add docs/tutorials/new_tutorial.*          # stage the files updated by pre-commit
git commit -m "Update new tutorial"  # commit to the branch

Release procedure#

Grain release can be done by running the “Build and Publish Release” workflow. It builds wheels for all supported platforms and uploads them to PyPI.

IMPORTANT! Please remember to bump version entry in MODULE.bazel and pyproject.toml files after each release. This will allow the nightly workflow to have correct identifier. E.g. if you just released 0.2.10, push a commit that moves version entry to the next anticipated release, such as 0.2.11 or 0.3.0.

Contents