Building this Documentation Locally

The problem is that Markdown rendering is not standardized and each renderer
can produce a slightly different output. That means the HTML version might be displayed
differently at readthedocs.org than at GitHub.

If you write a longer documentation it would be nice to see the result locally,
without need to push to GitHub and then fixing the result.

Prerequisites

You need to install mkdocs tool which is used for building the HTML documentation
at readthedocs.org. Run as root:

zypper in python-pip python-PyYAML python-devel
# mkdocs is not packaged, use pip to install it
pip install mkdocs

Building the Documentation

Manual Build

Local Documentation Server

If you work on the documentation and you want to see the current rendered version
then it is a good idea to run the documentation server. The advantage is that the
server watches the documentation changes and regenerates it automatically whenever
a file is modified. You just need to reload the file in the browser.

# run the server
mkdocs serve --clean
# open this local URL
xdg-open http://127.0.0.1:8000/README/