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 <olivier.gayot@canonical.com>

documentation/.gitignore

@@ -1 +1,2 @@
+/discourse/
 /html/

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
+.PHONY: html
-all: $(HTML)
+html: $(HTML)
+
+.PHONY: discourse
+discourse: $(DISCOURSE_MD)
 
 .PHONY: clean
 clean:
+	$(RM) $(DISCOURSE_MD)
+	$(RM) -d discourse
 	$(RM) $(HTML)
 	$(RM) -d html

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
 

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
 

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.
 
 <a name="commandlist"></a>
 

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:
 
-<pre><code><a href="/t/draft-automated-server-install-reference/16613#version">version</a>: 1
+<pre><code><a href="autoinstall-reference.md#version">version</a>: 1
-<a href="/t/draft-automated-server-install-reference/16613#reporting">reporting</a>:
+<a href="autoinstall-reference.md#reporting">reporting</a>:
     hook:
         type: webhook
         endpoint: http://example.com/endpoint/path
-<a href="/t/draft-automated-server-install-reference/16613#early-commands">early-commands</a>:
+<a href="autoinstall-reference.md#early-commands">early-commands</a>:
     - ping -c1 198.162.1.1
-<a href="/t/draft-automated-server-install-reference/16613#locale">locale</a>: en_US
+<a href="autoinstall-reference.md#locale">locale</a>: en_US
-<a href="/t/draft-automated-server-install-reference/16613#keyboard">keyboard</a>:
+<a href="autoinstall-reference.md#keyboard">keyboard</a>:
     layout: gb
     variant: dvorak
-<a href="/t/draft-automated-server-install-reference/16613#network">network</a>:
+<a href="autoinstall-reference.md#network">network</a>:
     network:
         version: 2
         ethernets:
@@ -87,8 +87,8 @@ Here is an example file that shows off most features:
                 parameters:
                     mode: active-backup
                     primary: enp3s0
-<a href="/t/draft-automated-server-install-reference/16613#proxy">proxy</a>: http://squid.internal:3128/
+<a href="autoinstall-reference.md#proxy">proxy</a>: http://squid.internal:3128/
-<a href="/t/draft-automated-server-install-reference/16613#apt">apt</a>:
+<a href="autoinstall-reference.md#apt">apt</a>:
     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
-<a href="/t/draft-automated-server-install-reference/16613#storage">storage</a>:
+<a href="autoinstall-reference.md#storage">storage</a>:
     layout:
         name: lvm
-<a href="/t/draft-automated-server-install-reference/16613#identity">identity</a>:
+<a href="autoinstall-reference.md#identity">identity</a>:
     hostname: hostname
     username: username
     password: $crypted_pass
-<a href="/t/draft-automated-server-install-reference/16613#ssh">ssh</a>:
+<a href="autoinstall-reference.md#ssh">ssh</a>:
     install-server: yes
     authorized-keys:
       - $key
     allow-pw: no
-<a href="/t/draft-automated-server-install-reference/16613#snaps">snaps</a>:
+<a href="autoinstall-reference.md#snaps">snaps</a>:
     - name: go
       channel: 1.14/stable
       classic: true
-<a href="/t/draft-automated-server-install-reference/16613#debconf-selections">debconf-selections</a>: |
+<a href="autoinstall-reference.md#debconf-selections">debconf-selections</a>: |
     bind9      bind9/run-resolvconf    boolean false
-<a href="/t/draft-automated-server-install-reference/16613#packages">packages</a>:
+<a href="autoinstall-reference.md#packages">packages</a>:
     - libreoffice
     - dns-server^
-<a href="/t/draft-automated-server-install-reference/16613#user-data">user-data</a>:
+<a href="autoinstall-reference.md#user-data">user-data</a>:
     disable_root: false
-<a href="/t/draft-automated-server-install-reference/16613#late-commands">late-commands</a>:
+<a href="autoinstall-reference.md#late-commands">late-commands</a>:
     - sed -ie 's/GRUB_TIMEOUT=.*/GRUB_TIMEOUT=30/' /target/etc/default/grub
-<a href="/t/draft-automated-server-install-reference/16613#error-commands">error-commands</a>:
+<a href="autoinstall-reference.md#error-commands">error-commands</a>:
     - tar c /var/log/installer | nc 192.168.0.1 1000
 </code></pre>
 
@@ -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
 

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()