Contributing
Documenting
We use mkdocs-material to easily generate documentation from markdown.
Installing Dependencies
sudo apt-get update
sudo apt-get -y install python3-pip
sudo apt-get -y install mkdocs
pip3 install mkdocs-material mike
Testing
To quickly test the version of the documentation you're using, without commiting
anything to the gh-pages
branch, run the following command.
mkdocs serve --dev-addr=0.0.0.0:8000
Deploying
We use mike to maintain multiple versions of the documentation. To build the documentation with mike, call
mike deploy <tag>
This will build the documentation, and add a static version of the site under the
gh-pages
branch. For example, to deploy the master documentation we do
mike deploy master
To set the default documentation version to master we would do.
mike set-default master
To push the documentation to Github Pages.
mike deploy master --push
Adding a new page
Mkdocs looks for documentation under the docs
folder. To add a new documentation page, you will need to first add the file
either directly to the docs
folder, or to a different folder with a symbolic link to the docs
folder. For example, say we wanted to add a page named MAINTAINERS.md
to the root of the project
First, we create the file at the root of the project
touch MAINTAINERS.md
Next, we add a symbolic link to the docs folder
cd docs/reference
ln -s ../../MAINTAINERS.md .
Finally, we add the file to our navigation in mkdocs.yml
- nav:
- Reference:
- 'Maintainers': reference/MAINTAINERS.md
Now, when you build the documentation you should see the page that we've added in the "Reference" section with the title "Maintainers".
Updating the Changelog
We follow the guidance of Keep a Changelog for best practices in maintaining a chronological human-readable CHANGELOG.md file. If the change is worth developers and users knowing about, consider adding an entry to the change log.