add html documentation generation through sphinx

makefile: add a target to install sphinx and build static HTML documentation from markdown, locally

Makefile

@@ -93,3 +93,25 @@ update_todo:
 	echo '<!-- This file is automatically generated by "make update_todo" -->' > doc/md/TODO.md
 	./gitea-cli/bin/gitea issues zerodb/debian-live-config | jq -r '.[] | "- #\(.number) - \(.title)"' >> doc/md/TODO.md; \
 	rm -rf gitea-cli
+
+doc: install_dev_docs doc_md doc_html
+
+# install documentation generator (sphinx + markdown + theme)
+install_dev_docs:
+	python3 -m venv .venv/
+	source .venv/bin/activate && pip3 install sphinx recommonmark sphinx_rtd_theme
+
+doc_md:
+	cp README.md doc/md/index.md
+	cp CHANGELOG.md doc/md/
+	cp LICENSE doc/md/LICENSE.md
+	sed -i 's|doc/md/||g' doc/md/*.md
+	./doc/gen_package_lists.py
+
+# HTML documentation generation (sphinx-build --help)
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = doc/md    # répertoire source (markdown)
+BUILDDIR      = doc/html  # répertoire destination (html)
+doc_html:
+	source .venv/bin/activate && sphinx-build -c doc/md -b html doc/md doc/html

doc/md/conf.py

@@ -0,0 +1,83 @@
+# Configuration file for the Sphinx documentation builder.
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+
+project = 'debian-live-config'
+author = 'nodiscc@gmail.com'
+version = '2.3'
+release = '2.3'
+html_show_copyright = True
+
+# -- General configuration ---------------------------------------------------
+
+# 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']
+
+# Only parse .md files
+source_suffix = ['.md']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+html_show_sphinx = True
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+html_css_files = ['style.css']
+
+# The master toctree document.
+master_doc = 'index'
+
+html_theme_options = {
+    'display_version': True,
+    'prev_next_buttons_location': 'bottom',
+    'style_external_links': True,
+    'vcs_pageview_mode': 'edit',
+    'collapse_navigation': False,
+    'sticky_navigation': True,
+    'navigation_depth': 2, # Defines sidebar navigation depth
+    'titles_only': False
+}
+
+html_context = {
+    "display_gitlab": True, # Integrate Gitlab
+    "gitlab_host": "gitlab.com",
+    "gitlab_user": "nodiscc", # Username
+    "gitlab_repo": "debian-live-config", # Repo name
+    "gitlab_version": "master", # Version
+    "conf_py_path": "/doc/md/" # Path in the checkout to the docs root
+}
+
+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