From 36a89758161478e2f0c8f2bea4c51db456672efa Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 19 Jun 2020 13:46:04 +0200 Subject: add SETUP file --- SETUP.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 SETUP.md diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..53d419c --- /dev/null +++ b/SETUP.md @@ -0,0 +1,68 @@ +# 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` to syncronize your changes with others: + + sudo apt install git + +To generate a website from the collection of source files, +you additionally need `Make` and `MKDocs` +(but you don't need `LESS` which gets included by default, +so can suppress installing that): + + sudo apt install make 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 -- cgit v1.2.3