HNAP Manual

This manual is mkdocs based. It supports documentation of multiple versions using the mike utility.

Install mkdocs, mkdocs-material and pdf-export-plugin

python -m pip install -r requirements.txt

You might want to work in a Python virtualenv:

virtualenv --python=/usr/bin/python3 venv/
source venv/bin/activate
python -m pip install -r requirements.txt

Important: Each file name needs to be the same as the first heading in each file.

View documentation locally

mike serve

This command starts a local webserver at localhost:8000.

Add a new version

mike deploy <version> <alias> <-u> <-p>

<version> is the version number of the documentation (e.g. 1.0.0).
<alias> is an alias for this version. Currently, we use the alias latest to set the version which is automatically shown when visiting the website.

If the version number (e.g. 1.0.0) already exists, you have to add -u (for update) to the command.

Deploy to Github Pages

To push the content to Github, add -p.

This will build the static files and push to the gh-pages branch on Github, so they will be served automatically at manual.hnap.de.

So a complete command might look like this:

mike deploy 1.0.0 latest -u -p

Generate PDF

Currently, the mkdocs-pdf-export-plugin can't handle anchors, therefore it is necessary to temporarily alter links containing anchors i.e. from "(../foo#bar)" to "(../foo.md#bar)" to be able to generate a PDF file.

export ENABLE_PDF_EXPORT=1
mkdocs build