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
