Documentation

The core documentation for ActivitySim is built with Sphinx. The input files for this documentation can be written either in markdown with filenames ending in .md (preferred for new documentation pages) or reStructuredText with filenames ending in .rst. In addition to converting *.md and *.rst files to html format, Sphinx can also read the inline Python docstrings and convert them into html as well. ActivitySim’s docstrings are written in numpydoc format.

Building the Documentation

Developers who want to test a build of the ActivitySim documentation locally can do so using sphinx. A pre-packaged conda environment is available to simplify this process. On the command line, starting from the activitysim directory that constitutes the main repository (i.e. you should see subdirectories including activitysim, conda-environments, docs, and a few others) run these commands:

mkdir -p ../.env
mamba env update -p ../.env/DOCBUILD -f conda-environments/docbuild.yml
conda activate ../.env/DOCBUILD
cd docs
make clean
make html

This will build the docs in the docs/_build/html directory. They can be viewed in a web browser using the file:/// protocol, or by double-clicking on the index.html file (or any other .html file in that directory).

Automatic Documentation Builds

Documentation can also be rendered online automatically by GitHub. Several scripts are included in this repository’s GitHub Actions to do so when updates are made to the main or develop branches in the primary ActivitySim repository.

If you are working in a fork of the primary ActivitySim/activitysim repository, you can generate test builds of the documentation by pushing a commit to your branch with the tag [makedocs] in the commit message. Note to prevent conflicts this only works on a fork, not within the primary ActivitySim repository, and only on branches named something other than develop. The documentation will then be published on your own subdomain. For example, if your fork is tacocat/activitysim, and you are working on the featuring-cilantro branch, the GitHub will render your documentation build at https://tacocat.github.io/activitysim/featuring-cilantro.