# Setting up feature documentation

> Setup feature documentation for reading, editing, or publishing

This documents setting up the feature documentation system,
either for reading or editing the source files,
or for generating a website
e.g. for public display.


## Prerequisites

For reading or editing documentation files,
you only need some plain-text editor
(e.g. `nano`, `vim`, `emacs`, or `mcedit`),
and `git` and `myrepos` to syncronize your changes with others:

    sudo apt install git myrepos

For generating website from the collection of source files,
you additionally need `MKDocs` and some helper tools:

    sudo apt install make w3c-linkchecker libtext-hogan-perl mkdocs

For checking quality of generated website,
you need an extra helper tool:

    sudo apt install w3c-linkchecker


## Fetch features

The documentation is grouped by "feature",
each tracked in a separate git.
All features are pulled together in the git "features"
using this command:

    make init

You can repeat the command later,
e.g. after updating the "features" git
where additional features added.

Simple re-init may fail, however
(e.g. after a git update _removing_ some features).
More reliable is to do a [cleanup|#Cleanup]
and then a fresh init.


## Build website

This command generates a website from the feature texts:

    make


## Check website

This command checks generated website for flaws in links:

    make check


## Cleanup

All fetched and generated files can be removed
with this command:

    make distclean

Alternatively
(e.g. when needing to clean while offline),
this command removed only generated files:

    make clean