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 (limited to '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 From 3c95a1b3bf357d55192829642bd2cbc08e2183ce Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 19 Jun 2020 14:17:12 +0200 Subject: SETUP: fix install all needed packages --- SETUP.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'SETUP.md') diff --git a/SETUP.md b/SETUP.md index 53d419c..cf291d1 100644 --- a/SETUP.md +++ b/SETUP.md @@ -13,16 +13,16 @@ e.g. for public display. 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: +and `git` and `myrepos` to syncronize your changes with others: - sudo apt install git + sudo apt install git myrepos To generate a website from the collection of source files, -you additionally need `Make` and `MKDocs` +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 mkdocs less- + 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). -- cgit v1.2.3 From ff8bc6ba9f5dc6dc7e831ccb11aa16734d9c41dd Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 19 Jun 2020 15:32:34 +0200 Subject: SETUP: drop risky suggestion to avoid less --- SETUP.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) (limited to 'SETUP.md') diff --git a/SETUP.md b/SETUP.md index cf291d1..d057a91 100644 --- a/SETUP.md +++ b/SETUP.md @@ -18,14 +18,9 @@ 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): +you additionally need `MKDocs` and some helper tools. - 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). + sudo apt install make w3c-linkchecker libtext-hogan-perl mkdocs ## Fetch features -- cgit v1.2.3 From 39c076d3f9011307837d175d99ffccd960eccf63 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 19 Jun 2020 15:34:03 +0200 Subject: SETUP: tidy syntax slightly --- SETUP.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'SETUP.md') diff --git a/SETUP.md b/SETUP.md index d057a91..14e6c60 100644 --- a/SETUP.md +++ b/SETUP.md @@ -10,15 +10,15 @@ e.g. for public display. ## Prerequisites -To edit documentation files, +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 -To generate a website from the collection of source files, -you additionally need `MKDocs` and some helper tools. +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 -- cgit v1.2.3 From ef054635fa74005a04e85eba4b7f478f64981d57 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 19 Jun 2020 15:37:31 +0200 Subject: add command: make check --- Makefile | 2 ++ SETUP.md | 12 ++++++++++++ 2 files changed, 14 insertions(+) (limited to 'SETUP.md') diff --git a/Makefile b/Makefile index 0137e88..9ef3a86 100644 --- a/Makefile +++ b/Makefile @@ -20,6 +20,8 @@ all: doc doc: docs $(patsubst %,docs/%,$(subst -,/,$(notdir $(wildcard source/*)))) mkdocs build + +check: checklink site/index.html docs: diff --git a/SETUP.md b/SETUP.md index 14e6c60..cd1492e 100644 --- a/SETUP.md +++ b/SETUP.md @@ -22,6 +22,11 @@ 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 @@ -49,6 +54,13 @@ 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 -- cgit v1.2.3