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
To edit 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
To generate a website from the collection of source files,
you additionally need MKDocs and some helper tools
(but you don't need LESS which gets included by default,
so can suppress installing that):
sudo apt install make w3c-linkchecker libtext-hogan-perl mkdocs less-
(if you use LESS elsewhere on your system,
then skip the less- part of above command).
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
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
