Contributing to Documentation
Summary
For the Pavona project, documentation is captured in Markdown and placed close to what it is documenting in the repository. It is viewable on the Pavona website or in GitHub web interface, as well as in plain text. Unlike the GitHub and plain text view, the website supplements the markdown documentation with auto-generated documentation from tools such as rustdoc.
The Markdown (guidelines for which can be found here) is rendered into a book for the website using mdBook with the structure being determined by the SUMMARY.md in the root of the repository.
The util/site/build-docs.sh script is used to build this book as well as the generated API documentation for C and Rust code.
Rules for how to write correct Markdown files can be found in the reference manual.
In order to run them, you’ll need some dependencies.
Most are covered by Install system dependencies in the Getting Started guide, along with the packages in python-requirements.txt.
Since the creation of documentation is based around the conversion from Markdown to HTML files, you also need
- Cargo, the Rust package manager
- mdbook, which can be installed using Cargo The documentation is written to use some project specific preprocessors.
Once the dependencies have been installed, the documentation can be built with util/site/build-docs.sh.
This also handles auto-generated content, such as the API documentation, which is generated by Doxygen.
Building Docs Locally
In order to run a local instance of the documentation server run the following command from the root of the project repository.
./util/site/build-docs.sh serve
This will execute the preprocessing, build the documentation, and finally start a local server. The output will indicate at which address the local instance can be accessed. The default is http://0.0.0.0:9000.
File Structure
Documentation pertaining to the content of a directory in the repo should be within a README.md in that repository.
Any additional documentation that does not belong to a subdirectory should be put in a doc sub-directory.
Images and other assets should also be put in this doc directory.
This structure is used from the very root of the project where the README.md describes the project as a whole and the doc directory holds general information about the project that cannot be wholly contained by another subdirectory.
CMDGEN
In an effort to make as much content viewable in plain text and GitHub as possible, auto-generated markdown is checked in within documentation files.
This is done with a tool called CMDGEN, that lives at ./util/cmdgen.py.
When invoked this script will search all given files for <!-- BEGIN CMDGEN * --> and <!-- END CMDGEN --> delimiters.
On each encounter, it will run the command in the ‘begin’ delimiter and check the commands output (stdout) matches the content that is between the delimiters.
Commonly one will run the following, which will go through every markdown file in the repository and, because the -u flag is given, update the content between the delimiters.
./util/cmdgen.py -u '**/*.md'
For example, when cmdgen is run with the ‘-u’ flag, the following snippet will result in the insertion of the AES register tables between the BEGIN and END lines.
# Registers
<!-- BEGIN CMDGEN #util/regtool.py -d ./hw/ip/aes/data/aes.hjson -->
<!-- END CMDGEN -->
Note, one should remove the # before the commands.
This is there so that CMDGEN doesn’t generate registers in this file.
The CMDGEN tool can also be invoked by the ./hw/Makefile using the target cmdgen, from the top of the repo
make -C hw cmdgen