Deprecated page: This article and the processes described herein have been deprecated. You can now make or suggest edits to the documentation by choosing the “Help improve this document in the forum” link, at the bottom of each documentation page. When editing, please follow the guidelines in the writing guide. Please make a note of this.
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.
Related documents:
Installation
Install the builder. On Ubuntu 16.04 LTS:
sudo snap install documentation-builder
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
Verification
You can point a web browser at individual HTML files but to make your verification more conclusive you will need a web server.
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
Points to consider
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.