+Building the HTML documentation
+-------------------------------
+
+The HTML documentation (as seen [on the PowerDNS docs site](https://doc.powerdns.com/authoritative/)) is built from ReStructured Text (rst) files located in `docs`. They are compiled into HTML files using [Sphinx](http://www.sphinx-doc.org/en/master/index.html), a documentation generator tool which is built in Python.
+
+**Using a normal Python installation**
+
+For those simply contributing to the documentation, this avoids needing to install the various build
+tools and other dependencies.
+
+Install Python 2.7 or Python 3 (preferable) if you don't yet have it installed. On some operating
+systems you may also have to install `python3-pip` or similarly named.
+
+Ubuntu 16.04 / 18.04
+
+```sh
+apt update
+apt install python3 python3-pip python3-venv
+```
+
+macOS (using homebrew)
+
+```sh
+brew install python3
+```
+
+Update your `pip` and install/update `virtualenv` to avoid problems:
+
+```sh
+# for python2, use "pip" instead of "pip3"
+pip3 install -U pip
+pip3 install -U virtualenv
+```
+
+Enter the repository's `docs` folder, set up the virtualenv, and install the requirements
+
+```sh
+cd docs
+# for python2, use "virtualenv .venv" instead
+python3 -m venv .venv
+source .venv/bin/activate
+# The virtualenv may use an older pip, so upgrade it again
+pip3 install -U pip setuptools setuptools-git
+# Now you can install the requirements
+pip3 install -r requirements.txt
+```
+
+Finally, you can build the documentation:
+
+```sh
+sphinx-build . html-docs
+```
+
+Note: If your shell has problems finding sphinx-build, try using `.venv/bin/sphinx-build` instead.
+
+The HTML documentation is now available in `html-docs`.
+
+**Using the build tools**
+
+This method is preferable for those who already have a working build environment for PowerDNS.
+
+Install the dependencies under "COMPILING", and run autoreconf if you haven't already:
+
+```sh
+autoreconf -vi
+```
+
+Enter the `docs` folder, and use make to build the HTML docs.
+
+```
+cd docs
+make html-docs
+```
+
+The HTML documentation will now be available in `html-docs`.
+
projects / thirdparty / pdns.git / blobdiff