Introduction¶
This documentation is built using MkDocs, a static site generator that is geared towards building project documentation. The documentation is created in the Markdown format, and it all resides in the docs directory in the repository. The organization of the documentation is controlled by the mkdocs.yml in the root of the repository.
Video version available
Some of the material in this tutorial is presented in our video, How to Build Documentation.
Prerequisites¶
You will need to have mkdocs software installed locally, as well as a required plugin and the MkDocs Material theme. Below we will show you how to install mkdocs using the Python language's pip tool. For more details on installing and using MkDocs visit the MkDocs installation guide.
-
Open a terminal window.
-
Install
mkdocs:Windows / Linux:
sudo -H pip install mkdocsmacOS:
pip3 install mkdocs -
Install plugin to enable display of the last revision date:
Windows / Linux:
sudo -H pip install mkdocs-git-revision-date-localized-pluginmacOS:
pip3 install mkdocs-git-revision-date-localized-plugin -
Install plugin to enable redirects:
Windows / Linux:
sudo -H pip install mkdocs-redirectsmacOS:
pip3 install mkdocs-redirects -
Install Material theme:
Windows / Linux:
sudo -H pip install mkdocs-materialmacOS:
pip3 install mkdocs-material
Build and Deploy documentation¶
Make sure you have all the submodules:
git submodule update --init --recursive
Documentation is build by running to the following command in the root of the repository:
mkdocs build --clean
This command will create a static site folder in the root of the repository.
You can preview any changes you have made to the documentation by running the following command:
mkdocs serve
And then visiting http://localhost:8111 in your browser.
To deploy documentation to GitHub Pages, issue the following command:
mkdocs gh-deploy --clean
To stop the mkdocs serve command just type the key combination "Control-c".