From c811cc72f892a48a955a816d82bd96801b029c64 Mon Sep 17 00:00:00 2001 From: Olivier Gayot Date: Wed, 19 Oct 2022 12:00:57 +0200 Subject: [PATCH] doc: implement link substitution mechanism Running 'make' or 'make html' will now convert the links to .md files into links to .html files so that the documentation can be browsed locally as HTML files. This will also produce the HTML output under html/. Running 'make discourse' will convert the links to .md files into links to the existing discourse pages. The output MD files will be placed under discourse/ Signed-off-by: Olivier Gayot --- documentation/.gitignore | 1 + documentation/Makefile | 24 ++++++++-- documentation/autoinstall-quickstart-s390x.md | 2 +- documentation/autoinstall-quickstart.md | 2 +- documentation/autoinstall-reference.md | 2 +- documentation/autoinstall.md | 40 ++++++++-------- documentation/substitute-links.py | 48 +++++++++++++++++++ 7 files changed, 91 insertions(+), 28 deletions(-) create mode 100644 documentation/substitute-links.py diff --git a/documentation/.gitignore b/documentation/.gitignore index ac7af2e8..2aa8485c 100644 --- a/documentation/.gitignore +++ b/documentation/.gitignore @@ -1 +1,2 @@ +/discourse/ /html/ diff --git a/documentation/Makefile b/documentation/Makefile index 92ad98b1..c02d827f 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -1,15 +1,29 @@ SRC = $(wildcard *.md) -HTML = $(addprefix html/, $(SRC:.md=.html)) -html/%.html: %.md +DISCOURSE_MD = $(addprefix discourse/, $(SRC)) +HTML_MD = $(addprefix html/, $(SRC)) +HTML = $(HTML_MD:.md=.html) + +discourse/%.md: %.md + @mkdir --parents discourse + python3 ./substitute-links.py md-to-discourse --input $^ --output $@ + +html/%.md: %.md @mkdir --parents html - markdown $^ > $@ + python3 ./substitute-links.py md-to-html --input $^ --output $@ + +%.html: %.md pandoc $^ --standalone --output $@ -.PHONY: all -all: $(HTML) +.PHONY: html +html: $(HTML) + +.PHONY: discourse +discourse: $(DISCOURSE_MD) .PHONY: clean clean: + $(RM) $(DISCOURSE_MD) + $(RM) -d discourse $(RM) $(HTML) $(RM) -d html diff --git a/documentation/autoinstall-quickstart-s390x.md b/documentation/autoinstall-quickstart-s390x.md index 3ca4a65c..152deb14 100644 --- a/documentation/autoinstall-quickstart-s390x.md +++ b/documentation/autoinstall-quickstart-s390x.md @@ -2,7 +2,7 @@ The intent of this page is to provide simple instructions to perform an autoinstall in a VM on your machine on s390x. -This page is just a slightly adapted page of [the autoinstall quickstart page](/t/draft-automated-server-install-quickstart/16614) mapped to s390x. +This page is just a slightly adapted page of [the autoinstall quickstart page](autoinstall-quickstart.md) mapped to s390x. ## Download an ISO diff --git a/documentation/autoinstall-quickstart.md b/documentation/autoinstall-quickstart.md index b165c784..002a0a22 100644 --- a/documentation/autoinstall-quickstart.md +++ b/documentation/autoinstall-quickstart.md @@ -2,7 +2,7 @@ The intent of this page is to provide simple instructions to perform an autoinstall in a VM on your machine. -This page assumes you are on the amd64 architecture. There is a version for [s390x](/t/draft-automated-server-install-quickstart-s390x/16616) too. +This page assumes you are on the amd64 architecture. There is a version for [s390x](autoinstall-quickstart-s390x.md) too. ## Providing the autoinstall data over the network diff --git a/documentation/autoinstall-reference.md b/documentation/autoinstall-reference.md index bd13ae15..fd594be9 100644 --- a/documentation/autoinstall-reference.md +++ b/documentation/autoinstall-reference.md @@ -6,7 +6,7 @@ The autoinstall file is YAML. At top level it must be a mapping containing the k ## Schema -Autoinstall configs [are validated against a JSON schema](/t/draft-automated-server-install-schema/16615) before they are used. +Autoinstall configs [are validated against a JSON schema](autoinstall-schema.md) before they are used. diff --git a/documentation/autoinstall.md b/documentation/autoinstall.md index 1adb3d24..eef4ed70 100644 --- a/documentation/autoinstall.md +++ b/documentation/autoinstall.md @@ -33,7 +33,7 @@ Even if a fully noninteractive autoinstall config is found, the server installer ## Quick start -So you just want to try it out? Well we have [the page for you](/t/draft-automated-server-install-quickstart/16614). +So you just want to try it out? Well we have [the page for you](autoinstall-quickstart.md). ## Creating an autoinstall config @@ -45,7 +45,7 @@ If you have a preseed file already, the [autoinstall-generator](https://snapcraf # The structure of an autoinstall config -The autoinstall config has [full documentation](/t/draft-automated-server-install-reference/16613). +The autoinstall config has [full documentation](autoinstall-reference.md). Technically speaking the config is not defined as a textual format, but cloud-init config is usually provided as YAML so that is the syntax the documentation uses. @@ -59,18 +59,18 @@ A minimal config is: Here is an example file that shows off most features: -
version: 1
-reporting:
+
version: 1
+reporting:
     hook:
         type: webhook
         endpoint: http://example.com/endpoint/path
-early-commands:
+early-commands:
     - ping -c1 198.162.1.1
-locale: en_US
-keyboard:
+locale: en_US
+keyboard:
     layout: gb
     variant: dvorak
-network:
+network:
     network:
         version: 2
         ethernets:
@@ -87,8 +87,8 @@ Here is an example file that shows off most features:
                 parameters:
                     mode: active-backup
                     primary: enp3s0
-proxy: http://squid.internal:3128/
-apt:
+proxy: http://squid.internal:3128/
+apt:
     primary:
         - arches: [default]
           uri: http://repo.internal/
@@ -96,32 +96,32 @@ Here is an example file that shows off most features:
         my-ppa.list:
             source: "deb http://ppa.launchpad.net/curtin-dev/test-archive/ubuntu $RELEASE main"
             keyid: B59D 5F15 97A5 04B7 E230  6DCA 0620 BBCF 0368 3F77
-storage:
+storage:
     layout:
         name: lvm
-identity:
+identity:
     hostname: hostname
     username: username
     password: $crypted_pass
-ssh:
+ssh:
     install-server: yes
     authorized-keys:
       - $key
     allow-pw: no
-snaps:
+snaps:
     - name: go
       channel: 1.14/stable
       classic: true
-debconf-selections: |
+debconf-selections: |
     bind9      bind9/run-resolvconf    boolean false
-packages:
+packages:
     - libreoffice
     - dns-server^
-user-data:
+user-data:
     disable_root: false
-late-commands:
+late-commands:
     - sed -ie 's/GRUB_TIMEOUT=.*/GRUB_TIMEOUT=30/' /target/etc/default/grub
-error-commands:
+error-commands:
     - tar c /var/log/installer | nc 192.168.0.1 1000
 

 
@@ -129,7 +129,7 @@ Many keys and values correspond straightforwardly to questions the installer ask
 
 # Error handling
 
-Progress through the installer is reported via the [`reporting`](/t/draft-automated-server-install-reference/16613#reporting) system, including errors. In addition, when a fatal error occurs, the [`error-commands`](/t/draft-automated-server-install-reference/16613#error-commands) are executed and the traceback printed to the console. The server then just waits.
+Progress through the installer is reported via the [`reporting`](autoinstall-reference.md#reporting) system, including errors. In addition, when a fatal error occurs, the [`error-commands`](autoinstall-reference.md#error-commands) are executed and the traceback printed to the console. The server then just waits.
 
 # Possible future directions
 
diff --git a/documentation/substitute-links.py b/documentation/substitute-links.py
new file mode 100644
index 00000000..88237f9e
--- /dev/null
+++ b/documentation/substitute-links.py
@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+
+import argparse
+from typing import List, Tuple
+
+discourse_substitutions = [
+    ("autoinstall.md", "/t/automated-server-installs/16612"),
+    ("autoinstall-reference.md", "/t/automated-server-install-reference/16613"),
+    ("autoinstall-quickstart.md", "/t/automated-server-install-quickstart/16614"),
+    ("autoinstall-schema.md", "t/automated-server-install-schema/16615"),
+    ("autoinstall-quickstart-s390x.md", "t/automated-server-install-schema/16616"),
+]
+md_to_html_substitutions = [
+    ("autoinstall.md", "autoinstall.html"),
+    ("autoinstall-reference.md", "autoinstall-reference.html"),
+    ("autoinstall-quickstart.md", "autoinstall-quickstart.html"),
+    ("autoinstall-schema.md", "autoinstall-schema.html"),
+    ("autoinstall-quickstart-s390x.md", "autoinstall-quickstart-s390x.html"),
+]
+
+def perform_substitutions(content: str, substitutions: List[Tuple[str, str]]) -> str:
+    for old, new in substitutions:
+        content = content.replace(old, new)
+    return content
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument("--input", "-i", type=argparse.FileType(mode="r"), default="-")
+    parser.add_argument("--output", "-o", type=argparse.FileType(mode="w"), default="-")
+    parser.add_argument("action", choices=("md-to-discourse", "md-to-html"))
+
+    args = vars(parser.parse_args())
+
+    if args["action"] == "md-to-discourse":
+        substitutions = discourse_substitutions
+    else:
+        substitutions = md_to_html_substitutions
+
+    print(perform_substitutions(
+            args["input"].read(),
+            substitutions=substitutions),
+        file=args["output"])
+
+
+if __name__ == "__main__":
+    main()