From 7282d816c8d70fa70e199ec8e4b5b679fbaa1caa Mon Sep 17 00:00:00 2001 From: Sarah Hoffmann Date: Wed, 7 Aug 2024 16:28:44 +0200 Subject: [PATCH 1/1] build vagrant instructions dynamically with mkdocs-gen-files --- Makefile | 10 +++++++- docs/admin/Installation.md | 4 ++-- docs/develop/Development-Environment.md | 17 ++++++------- docs/mk_install_instructions.py | 32 +++++++++++++++++++++++++ docs/mkdocs.yml => mkdocs.yml | 14 +++++++---- 5 files changed, 59 insertions(+), 18 deletions(-) create mode 100644 docs/mk_install_instructions.py rename docs/mkdocs.yml => mkdocs.yml (90%) diff --git a/Makefile b/Makefile index dae45322..29243583 100644 --- a/Makefile +++ b/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 diff --git a/docs/admin/Installation.md b/docs/admin/Installation.md index 9159ac62..cd561718 100644 --- 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: - * [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. diff --git a/docs/develop/Development-Environment.md b/docs/develop/Development-Environment.md index 19948e7c..1db32a6e 100644 --- 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-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 ``` diff --git a/docs/mk_install_instructions.py b/docs/mk_install_instructions.py new file mode 100644 index 00000000..f8edc89c --- /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 fa65a11b..c5f9b7bd 100644 --- a/docs/mkdocs.yml +++ b/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 -- 2.39.5