diff options
| -rw-r--r-- | .mrconfig | 23 | ||||
| -rw-r--r-- | Makefile | 15 | ||||
| -rw-r--r-- | SETUP.md | 75 | ||||
| -rw-r--r-- | TODO | 6 | ||||
| -rw-r--r-- | mkdocs.yml | 20 |
5 files changed, 123 insertions, 16 deletions
@@ -1,21 +1,30 @@ [source/account] -checkout = git clone 'https://source.virtual-assembly.org/feature/account.git' 'account' +checkout = git clone 'git://source.virtual-assembly.org/feature/account.git' 'account' + +[source/account-secure] +checkout = git clone 'git://source.redpill.dk/account-secure.git' 'account-secure' [source/account-shell] -checkout = git clone 'https://source.virtual-assembly.org/feature/account-shell.git' 'account-shell' +checkout = git clone 'git://source.virtual-assembly.org/feature/account-shell.git' 'account-shell' + +[source/accounting] +checkout = git clone 'git://source.couchdesign.dk/accounting.git' 'accounting' [source/chat] -checkout = git clone 'https://source.virtual-assembly.org/feature/chat.git' 'chat' +checkout = git clone 'git://source.virtual-assembly.org/feature/chat.git' 'chat' [source/source] -checkout = git clone 'https://source.redpill.dk/source.git' 'source' +checkout = git clone 'git://source.redpill.dk/source.git' 'source' [source/system] -checkout = git clone 'https://source.redpill.dk/system.git' 'system' +checkout = git clone 'git://source.redpill.dk/system.git' 'system' + +[source/system-desktop] +checkout = git clone 'git://source.couchdesign.dk/system-desktop.git' 'system-desktop' [source/system-gateway] -checkout = git clone 'https://source.redpill.dk/system-gateway.git' 'system-gateway' +checkout = git clone 'git://source.redpill.dk/system-gateway.git' 'system-gateway' [source/about] -checkout = git clone 'https://source.couchdesign.dk/org.git' 'about' +checkout = git clone 'git://source.couchdesign.dk/org.git' 'about' @@ -1,4 +1,4 @@ -# Depends: myrepos git mkdocs linkchecker libtext-hogan-perl +# Depends: myrepos git mkdocs w3c-linkchecker libtext-hogan-perl domain ?= example.org shellhost ?= shell.$(domain) @@ -20,13 +20,16 @@ all: doc doc: docs $(patsubst %,docs/%,$(subst -,/,$(notdir $(wildcard source/*)))) mkdocs build - linkchecker site/index.html +check: + checklink site/index.html + +# TODO: drop symlink removal when 2020-06-19 is well in the past docs: mkdir -p docs - ln -sf ../README.md docs/index.md -# ln -sf ../USE.md docs/use.md -# ln -sf ../ADMIN.md docs/admin.md + find docs -type l -delete + $(MUSTACHE) < README.md > docs/index.md + $(MUSTACHE) < SETUP.md > docs/setup.md docs/%: source mkdir -p docs/$* @@ -50,4 +53,4 @@ clean: distclean: clean rm -rf source -.PHONY: all doc clean distclean +.PHONY: all doc check clean distclean diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..cd1492e --- /dev/null +++ b/SETUP.md @@ -0,0 +1,75 @@ +# 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 @@ -1,2 +1,8 @@ * Fail build if output html contains square brackets. * Implement po4a internationalisation and localization routines. + * define taxonomies + + fields (of interest) + + domains (of access control) + + state (of maturity/maintenance) + * define relationships + + doap-deps @@ -1,29 +1,43 @@ site_name: System features repo_url: https://source.couchdesign.dk/features.git/ +markdown_extensions: + - toc: + permalink: 'ยง' + - codehilite: + guess_lang: False nav: - Introductions: - Account: 'account/index.md' - 'Account shell': 'account/shell/index.md' + - 'Account security': 'account/secure/index.md' + - Accounting: 'accounting/index.md' - Chat: 'chat/index.md' - System: 'system/index.md' + - 'System desktop': 'system/desktop/index.md' - 'System gateway': 'system/gateway/index.md' - Source: 'source/index.md' - Use: # - Introduction: 'use.md' # - Account: 'account/use.md' - 'Account shell': 'account/shell/use.md' + - 'Account security': 'account/secure/use.md' + - Accounting: 'accounting/use.md' - Chat: 'chat/use.md' - Source: 'source/use.md' - Administration: # - Introduction: 'admin.md' - Account: 'account/admin.md' - 'Account shell': 'account/shell/admin.md' + - 'Account security setup': 'account/secure/setup.md' # - Chat: 'chat/admin.md' + - 'System desktop setup': 'system/desktop/setup.md' - 'System gateway setup': 'system/gateway/setup.md' - Development: # - Introduction: 'devel.md' - System: 'system/devel.md' - About: - - Structure: 'about/index.md' - - 'Technical setup': 'about/setup.md' - - 'Maintenance': 'about/admin.md' + - Website: 'index.md' + - 'Website setup': 'setup.md' + - 'Source structure': 'about/index.md' + - 'Source setup': 'about/setup.md' + - 'Source maintenance': 'about/admin.md' |