README.md

PyRTL's Documentation

PyRTL's documentation is published to Read the Docs at https://pyrtl.readthedocs.io/ . There is a build dashboard and the main configuration file is .readthedocs.yaml in the repository's root directory.

PyRTL's documentation is in this docs directory. It is built with Sphinx, and written in reStructuredText. The main Sphinx configuration file is docs/conf.py.

Most of PyRTL's documentation is automatically extracted from Python docstrings, see docstring formating for supported directives and fields. Sphinx parses Python type annotations, so put type information into annotations instead of docstrings.

Follow the instructions on this page to build a local copy of PyRTL's documentation. This is useful for verifying that PyRTL's documentation still renders correctly after making a local change.

There is additional PyRTL documentation in the gh-pages branch. This additional documentation is pushed to https://ucsbarchlab.github.io/PyRTL/ by the pages-build-deployment GitHub Action. The additional documentation is written in GitHub MarkDown, and is not described further in this README.

Installing Sphinx

Sphinx and its dependencies are all pinned to specific versions for reproducible documentation builds. This avoids problems where documentation builds randomly fail due to bugs or incompatibilities in the newest version of Sphinx or one of its dependencies.

Use of an environment manager like conda or virtualenv is strongly recommended. To install Sphinx locally, run the following commands from the repository root:

# Install Sphinx.
$ pip install --upgrade -r docs/requirements.txt

Installing Graphviz

Install graphviz. Use of a package manager like apt or brew is strongly recommended. Instructions vary depending on your operating system, see the installation link for details.

Running Sphinx

Run Sphinx with the provided docs/Makefile:

# Run Sphinx to build PyRTL's documentation.
$ make -C docs

A local copy of PyRTL's documentation should be available in docs/_build/html. docs/_build/html/index.html is the home page.

Updating Sphinx

To update the pinned version of Sphinx, run

# Run pip-compile to generate docs/requirements.txt from docs/requirements.in.
$ make -C docs requirements.txt

It's a good idea to update the pinned version of Sphinx whenever you update the documentation.