build vagrant instructions dynamically with mkdocs-gen-files

diff --git a/Makefile b/Makefile
index dae45322a0410980af4f2419065429c5ca065786..29243583431092b8b3f4812c84c5ea1a894290ec 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -29,4 +29,12 @@ lint:
 bdd:
        cd test/bdd; behave -DREMOVE_TEMPLATE=1
 
 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

diff --git a/docs/admin/Installation.md b/docs/admin/Installation.md
index 9159ac62666287b81f70b754a8b2caf985917065..cd561718ae485c158405848009eeead2e20f8b1d 100644 (file)
--- a/docs/admin/Installation.md
+++ b/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:
 
 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.
 
 These OS-specific instructions can also be found in executable form
 in the `vagrant/` directory.

diff --git a/docs/develop/Development-Environment.md b/docs/develop/Development-Environment.md
index 19948e7cc229bde18ce159462ec18e3211255fb3..1db32a6e3acda0dde831c5bf60e86a844fd8f4ab 100644 (file)
--- a/docs/develop/Development-Environment.md
+++ b/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](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
 
 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\
 ```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
     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/)
 
 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
 
 ```
 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
 
 ```
 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:
 
 ```
 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
 ```
 [server:296] Serving on http://0.0.0.0:8088
 [handlers:62] Start watching changes
 ```

diff --git a/docs/mk_install_instructions.py b/docs/mk_install_instructions.py
new file mode 100644 (file)
index 0000000..f8edc89
--- /dev/null
+++ b/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")

diff --git a/docs/mkdocs.yml b/mkdocs.yml
similarity index 90%
rename from docs/mkdocs.yml
rename to mkdocs.yml
index fa65a11b97874ccbe001e8edc20b41846cccf840..c5f9b7bde8a40d78c5c25cb4eafd5fe37f0e7195 100644 (file)
--- a/docs/mkdocs.yml
+++ b/mkdocs.yml
@@ -4,7 +4,7 @@ theme:
   features:
     - navigation.tabs
 copyright: Copyright © Nominatim developer community
   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:
 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'
         - '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'
     - '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'
         - '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
 markdown_extensions:
     - codehilite
     - admonition


@@ -70,12 +69,17 @@ markdown_extensions:
     - toc:
         permalink: 
 extra_css: [extra.css, styles.css]
     - toc:
         permalink: 
 extra_css: [extra.css, styles.css]

+exclude_docs: |
+    mk_install_instructions.py

 plugins:
     - search
     - mkdocstrings:
         handlers:
           python:
 plugins:
     - search
     - mkdocstrings:
         handlers:
           python:

-            paths: ["${PROJECT_SOURCE_DIR}/src"]
+            paths: ["src"]

             options:
               show_source: False
               show_bases: False
             options:
               show_source: False
               show_bases: False

+    - gen-files:
+        scripts:
+          - docs/mk_install_instructions.py