This folder generates the UrbanSim online documentation, hosted at https://udst.github.io/urbansim/.
HTML files are generated using Sphinx and hosted with GitHub Pages from the gh-pages branch of the repository. The online documentation is rendered and updated manually.
The files in docs/source, along with docstrings in the source code, determine what appears in the rendered documentation. Here's a good tutorial for Sphinx.
Install the copy of UrbanSim that the documentation is meant to reflect, along with the documentation tools. The test extra is needed too, because the API documentation imports the DataFrame explorer, whose dependencies are declared there.
pip install ".[docs,test]"
Build the documentation. Warnings are treated as errors, matching the check that runs in CI.
sphinx-build -E -W --keep-going -b html docs/source docs/build/html
The HTML files will show up in docs/build/html/.
Clone a second copy of the repository and check out the gh-pages branch. Copy over the updated HTML files, commit them, and push the changes to GitHub.