tools/readthedocs: fix documentation generation

- https://readthedocs.org/projects/xsrv/builds/22131377/: ModuleNotFoundError: No module named 'recommonmark'
- recommonmark is deprecated in favor of myst-parser readthedocs/recommonmark#221
- use sphinx_external_toc instead of AutoStructify to generate global TOC https://pypi.org/project/sphinx_external_toc/
- requirements must be listed explicitely in docs/requirements.txt (Could not import extension myst_parser (exception: No module named 'myst_parser'))

.readthedocs.yml

@@ -5,11 +5,15 @@
 # Required
 version: 2
 
-# Build documentation with MkDocs
+# Build documentation with Sphinx
 sphinx:
   configuration: doc/md/conf.py
 
 # Optionally set the version of Python and requirements required to build your docs
 # https://github.com/rtfd/readthedocs.org/issues/5250
 python:
-  version: 3.5
+  version: 3.5
+
+python:
+  install:
+    - requirements: doc/md/requirements.txt

Makefile

@@ -120,7 +120,7 @@ doc: install_dev_docs doc_package_lists doc_md doc_html
 .PHONY: install_dev_docs # install documentation generator (sphinx + markdown + theme)
 install_dev_docs:
 	python3 -m venv .venv/
-	source .venv/bin/activate && pip3 install sphinx recommonmark sphinx_rtd_theme
+	source .venv/bin/activate && pip3 install sphinx myst_parser sphinx_rtd_theme
 
 .PHONY: doc_md # generate markdown documentation
 doc_md:

doc/md/_toc.yml

@@ -0,0 +1,26 @@
+root: index.md
+entries:
+  - file: download-and-installation.md
+    title: Download and installation
+  - file: usage.md
+    title: Usage
+  - file: packages/utility.md
+    title: "Software: Utility"
+  - file: packages/network.md
+    title: "Software: Internet and network"
+  - file: packages/audio-video.md
+    title: "Software: Audio and video"
+  - file: packages/office.md
+    title: "Software: Office"
+  - file: packages/graphics.md
+    title: "Software: Graphics"
+  - file: packages/system.md
+    title: "Software: System"
+  - file: packages/development.md
+    title: "Software: Development"
+  - file: packages/games.md
+    title: "Software: Games"
+  - file: packages/extras.md
+    title: "Software: Extras"
+  - file: CHANGELOG.md
+    title: "Changelog"

doc/md/conf.py

@@ -14,7 +14,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['recommonmark', 'sphinx_rtd_theme']
+extensions = ['myst_parser', 'sphinx_rtd_theme', 'sphinx_external_toc']
 
 # Only parse .md files
 source_suffix = ['.md']
@@ -65,19 +65,3 @@
 }
 
 exclude_patterns = ['README.md']
-
-# Load the recommonmark auto TOC generator
-# It will find any section named as defined in 'auto_toc_tree_section',
-# find any bullet lists of relative markdown links
-# And use it to generate a TOC and populate the sidebar
-from recommonmark.parser import CommonMarkParser
-from recommonmark.transform import AutoStructify
-def setup(app):
-    app.add_config_value('recommonmark_config', {
-        'enable_auto_toc_tree': True,
-        'auto_toc_tree_section': 'Documentation',
-        'auto_toc_maxdepth': 1, # Defines in-place generated TOC depth, not the sidebar depth
-    }, True)
-    app.add_transform(AutoStructify)
-
-#TODO markdown tables are note rendered in sphinx

doc/md/requirements.txt

@@ -0,0 +1,4 @@
+sphinx
+myst-parser
+sphinx_external_toc
+sphinx_rtd_theme