From 012d6c9c285c8fb993bef05b55503819e030e817 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Sat, 2 Nov 2019 21:18:56 +0100 Subject: Add feature accounting. --- .mrconfig | 3 +++ mkdocs.yml | 2 ++ 2 files changed, 5 insertions(+) diff --git a/.mrconfig b/.mrconfig index ffcdbd4..6c59dda 100644 --- a/.mrconfig +++ b/.mrconfig @@ -5,6 +5,9 @@ checkout = git clone 'https://source.virtual-assembly.org/feature/account.git' ' [source/account-shell] checkout = git clone 'https://source.virtual-assembly.org/feature/account-shell.git' 'account-shell' +[source/accounting] +checkout = git clone 'https://source.couchdesign.dk/accounting.git' 'accounting' + [source/chat] checkout = git clone 'https://source.virtual-assembly.org/feature/chat.git' 'chat' diff --git a/mkdocs.yml b/mkdocs.yml index aa971f6..c1b689e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,6 +4,7 @@ nav: - Introductions: - Account: 'account/index.md' - 'Account shell': 'account/shell/index.md' + - Accounting: 'accounting/index.md' - Chat: 'chat/index.md' - System: 'system/index.md' - Source: 'source/index.md' @@ -11,6 +12,7 @@ nav: # - Introduction: 'use.md' # - Account: 'account/use.md' - 'Account shell': 'account/shell/use.md' + - Accounting: 'accounting/use.md' - Chat: 'chat/use.md' - Source: 'source/use.md' - Administration: -- cgit v1.2.3 From d788632520e75570ae7da1bb882cfc1b2c7b2038 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Sat, 2 Nov 2019 21:19:43 +0100 Subject: Update source URI. --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index c1b689e..94a4a2a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ site_name: System features -repo_url: https://source.virtual-assembly.org/features.git/ +repo_url: https://source.couchdesign.dk/features.git/ nav: - Introductions: - Account: 'account/index.md' -- cgit v1.2.3 From fb18a4c1c5e379b88018d5584cc2a7d746c55e27 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Sat, 2 Nov 2019 21:53:55 +0100 Subject: Add feature system-desktop. --- .mrconfig | 3 +++ mkdocs.yml | 2 ++ 2 files changed, 5 insertions(+) diff --git a/.mrconfig b/.mrconfig index 6c59dda..4099429 100644 --- a/.mrconfig +++ b/.mrconfig @@ -17,5 +17,8 @@ checkout = git clone 'https://source.redpill.dk/source.git' 'source' [source/system] checkout = git clone 'https://source.redpill.dk/system.git' 'system' +[source/system-desktop] +checkout = git clone 'https://source.couchdesign.dk/system-desktop.git' 'system-desktop' + [source/about] checkout = git clone 'https://source.couchdesign.dk/org.git' 'about' diff --git a/mkdocs.yml b/mkdocs.yml index 94a4a2a..27d120c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,6 +7,7 @@ nav: - Accounting: 'accounting/index.md' - Chat: 'chat/index.md' - System: 'system/index.md' + - 'System desktop': 'system/desktop/index.md' - Source: 'source/index.md' - Use: # - Introduction: 'use.md' @@ -20,6 +21,7 @@ nav: - Account: 'account/admin.md' - 'Account shell': 'account/shell/admin.md' # - Chat: 'chat/admin.md' + - 'System desktop setup': 'system/desktop/setup.md' - Development: # - Introduction: 'devel.md' - System: 'system/devel.md' -- cgit v1.2.3 From 916e384dd9d18029ca40a25d5f9ee4d24f3bb1ee Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Sat, 2 Nov 2019 21:55:59 +0100 Subject: Add feature account-secure. --- .mrconfig | 3 +++ mkdocs.yml | 3 +++ 2 files changed, 6 insertions(+) diff --git a/.mrconfig b/.mrconfig index 4099429..71687e0 100644 --- a/.mrconfig +++ b/.mrconfig @@ -2,6 +2,9 @@ [source/account] checkout = git clone 'https://source.virtual-assembly.org/feature/account.git' 'account' +[source/account-secure] +checkout = git clone 'https://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' diff --git a/mkdocs.yml b/mkdocs.yml index 27d120c..4f1a5ae 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,6 +4,7 @@ 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' @@ -13,6 +14,7 @@ nav: # - 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' @@ -20,6 +22,7 @@ nav: # - 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' - Development: -- cgit v1.2.3 From b16c281c7fbc430c26da7021930c95c588d4cb07 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Sun, 3 Nov 2019 18:40:23 +0100 Subject: add feature system-gateway --- .mrconfig | 3 +++ mkdocs.yml | 2 ++ 2 files changed, 5 insertions(+) diff --git a/.mrconfig b/.mrconfig index 71687e0..18e1af4 100644 --- a/.mrconfig +++ b/.mrconfig @@ -23,5 +23,8 @@ checkout = git clone 'https://source.redpill.dk/system.git' 'system' [source/system-desktop] checkout = git clone 'https://source.couchdesign.dk/system-desktop.git' 'system-desktop' +[source/system-gateway] +checkout = git clone 'https://source.redpill.dk/system-gateway.git' 'system-gateway' + [source/about] checkout = git clone 'https://source.couchdesign.dk/org.git' 'about' diff --git a/mkdocs.yml b/mkdocs.yml index 4f1a5ae..c976b82 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,7 @@ nav: - 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' @@ -25,6 +26,7 @@ nav: - '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' -- cgit v1.2.3 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 From fe7f7845fd2fb332c3be9b9082ec5b5524f2b563 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 19 Jun 2020 13:47:02 +0200 Subject: update TODO: add ideas on taxonomies and relationships --- TODO | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/TODO b/TODO index a954a9f..0dc895e 100644 --- a/TODO +++ b/TODO @@ -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 -- cgit v1.2.3 From 48a6ccf6c20c46d63f27bcda676f06640227bddf Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 19 Jun 2020 14:16:25 +0200 Subject: use w3c-linkchecker (not linkchecker: badly maintained in testing/unstable currently) --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index cd21f72..0137e88 100644 --- a/Makefile +++ b/Makefile @@ -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,7 +20,7 @@ all: doc doc: docs $(patsubst %,docs/%,$(subst -,/,$(notdir $(wildcard source/*)))) mkdocs build - linkchecker site/index.html + checklink site/index.html docs: mkdir -p docs -- 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(-) 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(-) 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(-) 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(+) 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 From 3cd1ade78e64a86364d2b3d33ab4e7338f64ab95 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 19 Jun 2020 16:36:42 +0200 Subject: enable markdown extensions permalink codehilite --- mkdocs.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index c976b82..5653cde 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,10 @@ 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' -- cgit v1.2.3 From 2ef9ca8d05ec1ab9e511484413b04882fbd90233 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 19 Jun 2020 16:45:12 +0200 Subject: mark build target check as phony --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 9ef3a86..9e85e63 100644 --- a/Makefile +++ b/Makefile @@ -52,4 +52,4 @@ clean: distclean: clean rm -rf source -.PHONY: all doc clean distclean +.PHONY: all doc check clean distclean -- cgit v1.2.3 From 69a405127b2039a467e108e9d5055e1223fd3e37 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 19 Jun 2020 17:18:26 +0200 Subject: mr: use git protocol (not https: broken currently at source.couchdesign.dk and source.redpill.dk --- .mrconfig | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/.mrconfig b/.mrconfig index 18e1af4..724a793 100644 --- a/.mrconfig +++ b/.mrconfig @@ -1,30 +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 'https://source.redpill.dk/account-secure.git' '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 'https://source.couchdesign.dk/accounting.git' '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 'https://source.couchdesign.dk/system-desktop.git' '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' -- cgit v1.2.3 From 83b92e26072029241e181f11a66301a2f7f8650f Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 19 Jun 2020 18:50:11 +0200 Subject: fix process mustache for front README --- Makefile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 9e85e63..3bd88cf 100644 --- a/Makefile +++ b/Makefile @@ -24,11 +24,11 @@ doc: docs $(patsubst %,docs/%,$(subst -,/,$(notdir $(wildcard source/*)))) 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 docs/%: source mkdir -p docs/$* -- cgit v1.2.3 From 8fe1e54f704d6a1eefff2109d578821cc0c52315 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Sat, 20 Jun 2020 10:42:22 +0200 Subject: include this SETUP as About → Website setup; Improve menu items below About MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Makefile | 1 + mkdocs.yml | 8 +++++--- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 3bd88cf..a6839fc 100644 --- a/Makefile +++ b/Makefile @@ -29,6 +29,7 @@ docs: mkdir -p docs find docs -type l -delete $(MUSTACHE) < README.md > docs/index.md + $(MUSTACHE) < SETUP.md > docs/setup.md docs/%: source mkdir -p docs/$* diff --git a/mkdocs.yml b/mkdocs.yml index 5653cde..baf9b19 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,6 +36,8 @@ nav: # - 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' -- cgit v1.2.3