Documentation

You’ve found something unclear in the documentation and want to give a try at explaining it better? Let’s see how.

Building

This documentation is built with MkDocs.

With Docker and make

You can build the documentation and test it locally (with live reloading), using the serve target:

  1. $ make serve
  2. docker build -t maesh-docs -f docs.Dockerfile ./
  3. # […]
  4. docker run  --rm -v /Users/kevinpollet/Documents/Dev/maesh/docs:/mkdocs  -p 8000:8000 maesh-docs mkdocs serve
  5. # […]
  6. INFO    -  Building documentation...
  7. INFO    -  Cleaning site directory
  8. [I 200408 14:36:33 server:296] Serving on http://0.0.0.0:8000
  9. [I 200408 14:36:33 handlers:62] Start watching changes
  10. [I 200408 14:36:33 handlers:64] Start detecting changes

Note

By default, the local documentation server listens on http://127.0.0.1:8000. To build the documentation without serving it locally, use the build target.

With MkDocs

First, make sure you have python and pip installed. MkDocs supports python versions 2.7.9+, 3.4, 3.5, 3.6 and 3.7.

  1. $ python --version
  2. Python 2.7.14
  4. $ pip --version
  5. pip 19.3.1 from /usr/local/lib/python2.7/site-packages/pip (python 2.7)

Then, install MkDocs with pip.

  1. pip install --user -r requirements.txt

To build the documentation and serve it locally, run mkdocs serve from the root directory. This starts a local server, and exposes the documentation on http://127.0.0.1:8000:

  1. $ mkdocs serve
  2. INFO    -  Building documentation...
  3. INFO    -  Cleaning site directory
  4. [I 160505 22:31:24 server:281] Serving on http://127.0.0.1:8000
  5. [I 160505 22:31:24 handlers:59] Start watching changes
  6. [I 160505 22:31:24 handlers:61] Start detecting changes

Checking

To check that the documentation meets standard expectations (no dead links, html markup validity, …), use the verify target. If you’ve made changes to the documentation, it’s safer to clean it before verifying it.

  1. $ make clean verify
  2. docker build -t maesh-docs -f docs.Dockerfile ./
  3. # […]
  4. docker run --rm -v /Users/kevinpollet/Documents/Dev/maesh/docs:/mkdocs  -p 8000:8000 maesh-docs sh -c "mkdocs build && chown -R 501:20 ./site"
  5. === Checking HTML content...
  6. # […]

Disabling Verification

Verification can be disabled by setting the environment variable DOCS_VERIFY_SKIP to true:

  1. $ DOCS_VERIFY_SKIP=true make verify
  2. # […]
  3. DOCS_VERIFY_SKIP is true: no verification done.