doc/manpages: add the man pages to the docs

Generate the man pages for the `lxc` command and add them to
the reference documentation.

Signed-off-by: Ruth Fuchss <[email protected]>

.gitignore

@@ -20,6 +20,7 @@ test/syscall/sysinfo/sysinfo
 
 # Sphinx
 doc/html/
+doc/reference/manpages/**/*.md
 doc/config_options.txt
 doc/config_options.yaml
 doc/.sphinx/deps/

Makefile

@@ -118,6 +118,7 @@ doc-setup:
 	@echo "Setting up documentation build environment"
 	python3 -m venv doc/.sphinx/venv
 	. $(SPHINXENV) ; pip install --upgrade -r doc/.sphinx/requirements.txt
+	rm -f doc/reference/manpages/*.md
 	rm -Rf doc/html
 
 .PHONY: generate-config

doc/conf.py

@@ -1,12 +1,14 @@
 import contextlib
 import datetime
-import os
+import os,stat
 import subprocess
 import sys
 import tempfile
 import yaml
 from git import Repo
 import wget
+import subprocess
+import filecmp
 
 # Download and link swagger-ui files
 if not os.path.isdir('.sphinx/deps/swagger-ui'):
@@ -21,6 +23,74 @@
 if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui.css'):
     os.symlink('../../deps/swagger-ui/dist/swagger-ui.css', '.sphinx/_static/swagger-ui/swagger-ui.css')
 
+### MAN PAGES ###
+
+# Download lxc client
+
+if not os.path.isfile('.sphinx/deps/bin.linux.lxc'):
+     wget.download("https://github.com/canonical/lxd/releases/latest/download/bin.linux.lxc", ".sphinx/deps/bin.linux.lxc")
+     os.chmod('.sphinx/deps/bin.linux.lxc',stat.S_IEXEC)
+
+# Generate man pages content
+
+os.makedirs('.sphinx/deps/manpages', exist_ok=True)
+subprocess.run([".sphinx/deps/bin.linux.lxc","manpage", ".sphinx/deps/manpages/","--format=md"],check=True)
+
+# Preprocess man pages content
+
+for page in [x for x in os.listdir('.sphinx/deps/manpages') if os.path.isfile('.sphinx/deps/manpages/'+x)]:
+
+    # replace underscores with slashes to create a directory structure
+    pagepath = page.replace("_","/")
+
+    # for each generated page, add an anchor, fix the title, and adjust the heading levels
+    with open(os.path.join('.sphinx/deps/manpages/',page), 'r') as mdfile:
+        content = mdfile.readlines()
+
+    os.makedirs(os.path.dirname(os.path.join('.sphinx/deps/manpages/',pagepath)),
+                exist_ok=True)
+
+    with open(os.path.join('.sphinx/deps/manpages/',pagepath), 'w') as mdfile:
+        mdfile.write('('+page+')=\n')
+        for line in content:
+            if line.startswith("###### Auto generated"):
+                continue
+            elif line.startswith("## "):
+                mdfile.write("# `"+line[3:].rstrip()+"`\n")
+            elif line.startswith("##"):
+                mdfile.write(line[1:])
+            else:
+                mdfile.write(line)
+
+    # remove the input page (unless the file path doesn't change)
+    if "_" in page:
+        os.remove(os.path.join('.sphinx/deps/manpages/',page))
+
+# Complete and copy man pages content
+
+for folder, subfolders, files in os.walk('.sphinx/deps/manpages'):
+
+    # for each subfolder, add toctrees to the parent page that include the subpages
+    for subfolder in subfolders:
+        with open(os.path.join(folder,subfolder+'.md'), 'a') as parent:
+            parent.write('```{toctree}\n:titlesonly:\n:glob:\n:hidden:\n\n' +
+                         subfolder + '/*\n```\n')
+
+    # for each file, if the content is different to what has been generated before,
+    # copy the file to the reference/manpages folder
+    # (copying all would mess up the incremental build)
+    for f in files:
+        sourcefile = os.path.join(folder,f)
+        targetfile = os.path.join('reference/manpages/',os.path.relpath(folder,'.sphinx/deps/manpages'),f)
+
+        if (not os.path.isfile(targetfile) or
+            not filecmp.cmp(sourcefile,targetfile, shallow=False)):
+
+            os.makedirs(os.path.dirname(targetfile), exist_ok=True)
+            os.system('cp '+sourcefile+' '+targetfile)
+
+### End MAN PAGES ###
+
 # Project config.
 project = "LXD"
 author = "LXD contributors"

doc/reference/index.md

@@ -5,6 +5,7 @@ The reference material in this section provides technical descriptions of LXD.
 
 ```{toctree}
 :titlesonly:
+:maxdepth: 2
 
 /architectures
 /reference/cluster_member_config
@@ -13,6 +14,7 @@ Container environment </container-environment>
 /reference/image_format
 /explanation/instance_config
 /internals
+/reference/manpages
 /reference/networks
 Production server settings </reference/server_settings>
 /reference/projects

doc/reference/manpages.md

@@ -0,0 +1,9 @@
+(manpages)=
+# Man pages
+
+```{toctree}
+:titlesonly:
+:glob:
+
+manpages/*
+```

doc/reference/manpages/readme.txt

@@ -0,0 +1,3 @@
+The Markdown files in this directory are generated automatically
+from the man pages. They can therefore not be modified, and they
+should not be added to Git.