build vagrant instructions dynamically with mkdocs-gen-files

Makefile

@@ -29,4 +29,12 @@ lint:
 bdd:
 	cd test/bdd; behave -DREMOVE_TEMPLATE=1
 
-.PHONY: tests mypy pytest lint bdd build clean-build build-db build-api
+# Documentation
+
+doc:
+	mkdocs build
+
+serve-doc:
+	mkdocs serve
+
+.PHONY: tests mypy pytest lint bdd build clean-build build-db build-api doc serve-doc

docs/admin/Installation.md

@@ -4,8 +4,8 @@ This page contains generic installation instructions for Nominatim and its
 prerequisites. There are also step-by-step instructions available for
 the following operating systems:
 
-  * [Ubuntu 24.04](../appendix/Install-on-Ubuntu-24.md)
-  * [Ubuntu 22.04](../appendix/Install-on-Ubuntu-22.md)
+  * [Ubuntu 24.04](Install-on-Ubuntu-24.md)
+  * [Ubuntu 22.04](Install-on-Ubuntu-22.md)
 
 These OS-specific instructions can also be found in executable form
 in the `vagrant/` directory.

docs/develop/Development-Environment.md

@@ -49,6 +49,7 @@ The documentation is built with mkdocs:
 * [mkdocs](https://www.mkdocs.org/) >= 1.1.2
 * [mkdocstrings](https://mkdocstrings.github.io/) >= 0.25
 * [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)
+* [mkdocs-gen-files](https://oprypin.github.io/mkdocs-gen-files/)
 
 Please be aware that tests always run against the globally installed
 osm2pgsql, so you need to have this set up. If you want to test against
@@ -66,9 +67,9 @@ To set up the virtual environment with all necessary packages run:
 ```sh
 virtualenv ~/nominatim-dev-venv
 ~/nominatim-dev-venv/bin/pip install\
-    psycopg2-binary psutil psycopg[binary] PyICU SQLAlchemy \
-    python-dotenv jinja2 pyYAML datrie \
-    behave mkdocs mkdocstrings pytest pytest-asyncio pylint \
+    psutil psycopg[binary] PyICU SQLAlchemy \
+    python-dotenv jinja2 pyYAML datrie behave \
+    mkdocs mkdocstrings mkdocs-gen-files pytest pytest-asyncio pylint \
     types-jinja2 types-markupsafe types-psutil types-psycopg2 \
     types-pygments types-pyyaml types-requests types-ujson \
     types-urllib3 typing-extensions unicorn falcon
@@ -147,18 +148,14 @@ built using the [MkDocs](https://www.mkdocs.org/) static site generation
 framework. The master branch is automatically deployed every night on
 [https://nominatim.org/release-docs/develop/](https://nominatim.org/release-docs/develop/)
 
-To build the documentation, go to the build directory and run
+To build the documentation run
 
 ```
 make doc
-INFO - Cleaning site directory
-INFO - Building documentation to directory: /home/vagrant/build/site-html
 ```
 
-This runs `mkdocs build` plus extra transformation of some files and adds
-symlinks (see `CMakeLists.txt` for the exact steps).
 
-Now you can start webserver for local testing
+For local testing, you can start webserver:
 
 ```
 build> make serve-doc
@@ -170,7 +167,7 @@ If you develop inside a Vagrant virtual machine, use a port that is forwarded
 to your host:
 
 ```
-build> PYTHONPATH=$SRCDIR mkdocs serve --dev-addr 0.0.0.0:8088
+build> mkdocs serve --dev-addr 0.0.0.0:8088
 [server:296] Serving on http://0.0.0.0:8088
 [handlers:62] Start watching changes
 ```

docs/mk_install_instructions.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This file is part of Nominatim. (https://nominatim.org)
+#
+# Copyright (C) 2024 by the Nominatim developer community.
+from pathlib import Path
+
+import mkdocs_gen_files
+
+VAGRANT_PATH = Path(__file__, '..', '..', 'vagrant').resolve()
+
+for infile in VAGRANT_PATH.glob('Install-on-*.sh'):
+    outfile = f"admin/{infile.stem}.md"
+    title = infile.stem.replace('-', ' ')
+
+    with mkdocs_gen_files.open(outfile, "w") as outfd, infile.open() as infd:
+        print("#", title, file=outfd)
+        has_empty = False
+        for line in infd:
+            line = line.rstrip()
+            docpos = line.find('#DOCS:')
+            if docpos >= 0:
+                line = line[docpos + 6:]
+            elif line == '#' or line.startswith('#!'):
+                line = ''
+            elif line.startswith('# '):
+                line = line[2:]
+            if line or not has_empty:
+                print(line, file=outfd)
+                has_empty = not bool(line)
+
+    mkdocs_gen_files.set_edit_path(outfile, "docs/mk_install_instructions.py")

mkdocs.yml

@@ -4,7 +4,7 @@ theme:
   features:
     - navigation.tabs
 copyright: Copyright © Nominatim developer community
-docs_dir: ${CMAKE_CURRENT_BINARY_DIR}
+docs_dir: docs
 site_url: https://nominatim.org
 repo_url: https://github.com/openstreetmap/Nominatim
 nav:
@@ -29,6 +29,8 @@ nav:
         - 'Maintenance' : 'admin/Maintenance.md'
         - 'Migration from older Versions' : 'admin/Migration.md'
         - 'Troubleshooting' : 'admin/Faq.md'
+        - 'Installation on Ubuntu 22' : 'admin/Install-on-Ubuntu-22.md'
+        - 'Installation on Ubuntu 24' : 'admin/Install-on-Ubuntu-24.md'
     - 'Customization Guide':
         - 'Overview': 'customize/Overview.md'
         - 'Import Styles': 'customize/Import-Styles.md'
@@ -57,9 +59,6 @@ nav:
         - 'Setup for Development' : 'develop/Development-Environment.md'
         - 'Testing' : 'develop/Testing.md'
         - 'External Data Sources': 'develop/data-sources.md'
-    - 'Appendix':
-        - 'Installation on Ubuntu 22' : 'appendix/Install-on-Ubuntu-22.md'
-        - 'Installation on Ubuntu 24' : 'appendix/Install-on-Ubuntu-24.md'
 markdown_extensions:
     - codehilite
     - admonition
@@ -70,12 +69,17 @@ markdown_extensions:
     - toc:
         permalink: 
 extra_css: [extra.css, styles.css]
+exclude_docs: |
+    mk_install_instructions.py
 plugins:
     - search
     - mkdocstrings:
         handlers:
           python:
-            paths: ["${PROJECT_SOURCE_DIR}/src"]
+            paths: ["src"]
             options:
               show_source: False
               show_bases: False
+    - gen-files:
+        scripts:
+          - docs/mk_install_instructions.py