Building the Docs

Every non-trivial contribution must first have its HTML built and verified before a pull request (PR) is made from it.

See the documentation-builder project for details of the actual tool.

Installation

Install the builder. On Ubuntu 16.04 LTS:

sudo snap install documentation-builder

Note: You will first need to install package squashfuse if you're doing this in a LXD container.

To build the HTML, while in the root of the MAAS docs repository:

documentation-builder

You can point a web browser at individual HTML files but to make your verification more conclusive you will need a web server.

See the Ubuntu Server Guide for instructions on setting up Apache. The DocumentRoot should be the build directory. To test, point your browser at:

http://127.0.0.1/en/contributing.html

Alternatively, you can use Python to start a simple HTTP server (port 8000). While in the build directory run:

python -m SimpleHTTPServer

With Python 3:

python3 -m http.server

Some things to consider during verification:

A linkchecker (either a system-wide tool or a browser add-on)
Images should show enough context (surrounding real estate) but not so much to make important details illegible.