Merge pull request #3503 from lonvia/mkdocs-without-cmake

Build documentation without CMake

diff --git a/.gitignore b/.gitignore
index 8e91f1e5cd5fe96a1602c5ff6b559e1a83efd600..23bcdb1c6b08a00b8367320430f829be4bba95f6 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,7 @@
 *.swp
 
 docs/develop/*.png
+site-html
 
 build
 dist

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 01a71a3c59f6fe99bd52ba87525461398a3d76ab..dd5c3110e3d5e89b750281220a5ce9745bf8371f 100644 (file)
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -46,8 +46,6 @@ set(BUILD_IMPORTER on CACHE BOOL "Build everything for importing/updating the da
 set(BUILD_API on CACHE BOOL "Build everything for the API server")
 set(BUILD_MODULE off CACHE BOOL "Build PostgreSQL module for legacy tokenizer")
 set(BUILD_TESTS on CACHE BOOL "Build test suite")
-set(BUILD_DOCS on CACHE BOOL "Build documentation")
-set(BUILD_MANPAGE on CACHE BOOL "Build Manual Page")
 set(BUILD_OSM2PGSQL on CACHE BOOL "Build osm2pgsql (expert only)")
 set(INSTALL_MUNIN_PLUGINS on CACHE BOOL "Install Munin plugins for supervising Nominatim")
 
@@ -188,22 +186,6 @@ if (BUILD_MODULE)
     add_subdirectory(module)
 endif()
 
-#-----------------------------------------------------------------------------
-# Documentation
-#-----------------------------------------------------------------------------
-
-if (BUILD_DOCS)
-   add_subdirectory(docs)
-endif()
-
-#-----------------------------------------------------------------------------
-# Manual page
-#-----------------------------------------------------------------------------
-
-if (BUILD_MANPAGE)
-   add_subdirectory(man)
-endif()
-
 #-----------------------------------------------------------------------------
 # Installation
 #-----------------------------------------------------------------------------

diff --git a/Makefile b/Makefile
index dae45322a0410980af4f2419065429c5ca065786..cd7280fe193175eb2412f0de5719f32caf237ded 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -29,4 +29,16 @@ 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
+
+manpage:
+       argparse-manpage --pyfile man/create-manpage.py --function get_parser --project-name Nominatim --url https://nominatim.org  > man/nominatim.1 --author 'the Nominatim developer community' --author-email info@nominatim.org
+
+
+.PHONY: tests mypy pytest lint bdd build clean-build build-db build-api doc serve-doc manpage

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
deleted file mode 100644 (file)
index 8f864ec..0000000
--- a/docs/CMakeLists.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-# Auto-generated vagrant install documentation
-
-
-# build the actual documentation
-
-configure_file(mkdocs.yml ../mkdocs.yml)
-file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/appendix)
-
-set (DOC_SOURCES
-     admin
-     develop
-     api
-     customize
-     library
-     index.md
-     extra.css
-     styles.css
-    )
-
-foreach (src ${DOC_SOURCES})
-    execute_process(
-        COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/${src} ${CMAKE_CURRENT_BINARY_DIR}/${src}
-    )
-endforeach()
-
-ADD_CUSTOM_TARGET(doc
-   COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/bash2md.sh ${PROJECT_SOURCE_DIR}/vagrant/Install-on-Ubuntu-24.sh ${CMAKE_CURRENT_BINARY_DIR}/appendix/Install-on-Ubuntu-24.md
-   COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/bash2md.sh ${PROJECT_SOURCE_DIR}/vagrant/Install-on-Ubuntu-22.sh ${CMAKE_CURRENT_BINARY_DIR}/appendix/Install-on-Ubuntu-22.md
-   COMMAND mkdocs build -d ${CMAKE_CURRENT_BINARY_DIR}/../site-html -f ${CMAKE_CURRENT_BINARY_DIR}/../mkdocs.yml
-)
-
-ADD_CUSTOM_TARGET(serve-doc
-    COMMAND mkdocs serve -f ${CMAKE_CURRENT_BINARY_DIR}/../mkdocs.yml
-    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
-)

diff --git a/docs/admin/Deployment-Python.md b/docs/admin/Deployment-Python.md
index 821a2c06d994793639216177652586b08be72d66..9275bab86d536f6fcba5e61dcc08eda84ac0e9e7 100644 (file)
--- a/docs/admin/Deployment-Python.md
+++ b/docs/admin/Deployment-Python.md
@@ -19,8 +19,8 @@ to configure it.
 ### Installing the required packages
 
 The Nominatim frontend is best run from its own virtual environment. If
-you have already created one for the database backend during
-[installation](Installation.md#Building-Nominatim), you can use that. Otherwise
+you have already created one for the database backend during the
+[installation](Installation.md#building-nominatim), you can use that. Otherwise
 create one now with:
 
 ```sh

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:
 
-  * [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/bash2md.sh b/docs/bash2md.sh
deleted file mode 100755 (executable)
index a62fbd1..0000000
--- a/docs/bash2md.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/bin/sh
-#
-# Extract markdown-formatted documentation from a source file
-#
-# Usage: bash2md.sh <infile> <outfile>
-
-sed '/^#!/d;s:^#\( \|$\)::;s/.*#DOCS://' $1 > $2

diff --git a/docs/customize/Tokenizers.md b/docs/customize/Tokenizers.md
index 6b811a9adb13004560064df2c8796e700e9fdea0..ee51fec05b1e98da8425a6596dfbe5fa725d7901 100644 (file)
--- a/docs/customize/Tokenizers.md
+++ b/docs/customize/Tokenizers.md
@@ -52,7 +52,7 @@ NOMINATIM_DATABASE_MODULE_PATH=<path to directory where nominatim.so resides>
 ```
 
 This is in particular useful when the database runs on a different server.
-See [Advanced installations](../admin/Advanced-Installations.md#importing-nominatim-to-an-external-postgresql-database) for details.
+See [Advanced installations](../admin/Advanced-Installations.md#using-an-external-postgresql-database) for details.
 
 There are no other configuration options for the legacy tokenizer. All
 normalization functions are hard-coded.

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-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/library/Input-Parameter-Types.md b/docs/library/Input-Parameter-Types.md
index 5c53773290fee36565b7396068b4414a7b390528..d27bc96ff9d78613a96553b0b0dcb1a45d5fa516 100644 (file)
--- a/docs/library/Input-Parameter-Types.md
+++ b/docs/library/Input-Parameter-Types.md
@@ -5,8 +5,8 @@ in the query functions of the API object.
 
 ## Place identification
 
-The [details](NominatimAPI.md#nominatim_api.core.NominatimAPI.details) and
-[lookup](NominatimAPI.md#nominatim_api.core.NominatimAPI.lookup) functions
+The [details](NominatimAPI.md#nominatim_api.NominatimAPI.details) and
+[lookup](NominatimAPI.md#nominatim_api.NominatimAPI.lookup) functions
 require references to places in the database. Below the possible
 types for place identification are listed. All types are dataclasses.
 

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/man/CMakeLists.txt b/man/CMakeLists.txt
deleted file mode 100644 (file)
index 144b9f4..0000000
--- a/man/CMakeLists.txt
+++ /dev/null
@@ -1,15 +0,0 @@
-# Creates and installs manual page
-
-configure_file(${CMAKE_CURRENT_SOURCE_DIR}/create-manpage.tmpl create_manpage.py)
-
-find_program(ARGPARSEMANPAGE argparse-manpage)
-
-ADD_CUSTOM_TARGET(manpage
-    COMMAND ${ARGPARSEMANPAGE} --pyfile ${CMAKE_CURRENT_BINARY_DIR}/create_manpage.py
-    --function get_parser --project-name Nominatim
-    --url https://nominatim.org  > ${CMAKE_CURRENT_SOURCE_DIR}/nominatim.1
-    --author 'the Nominatim developer community'
-    --author-email info@nominatim.org
-)
-
-install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/nominatim.1 DESTINATION share/man/man1 )

diff --git a/man/create-manpage.py b/man/create-manpage.py
new file mode 100644 (file)
index 0000000..94206c4
--- /dev/null
+++ b/man/create-manpage.py
@@ -0,0 +1,12 @@
+import sys
+import os
+from pathlib import Path
+
+sys.path.append(str(Path(__file__, '..', '..', 'src').resolve()))
+
+from nominatim_db.cli import get_set_parser
+
+def get_parser():
+    parser = get_set_parser()
+
+    return parser.parser

diff --git a/man/create-manpage.tmpl b/man/create-manpage.tmpl
deleted file mode 100644 (file)
index 427bcb6..0000000
--- a/man/create-manpage.tmpl
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/usr/bin/env python3
-import sys
-import os
-
-sys.path.append('@PROJECT_SOURCE_DIR@')
-
-from nominatim.cli import get_set_parser
-
-def get_parser():
-    parser = get_set_parser()
-
-    return parser.parser

diff --git a/man/nominatim.1 b/man/nominatim.1
index 22eed2c6e3d742b07a83b2642e43761994b64a20..94fc989c26debe7be4e324bf3ee3db652ccb5a78 100644 (file)
--- a/man/nominatim.1
+++ b/man/nominatim.1
@@ -3,7 +3,7 @@
 nominatim
 .SH SYNOPSIS
 .B nominatim
-[-h] {import,freeze,replication,special-phrases,add-data,index,refresh,admin,export,serve,search,reverse,lookup,details,status} ...
+[-h] [--version] {import,freeze,replication,special-phrases,add-data,index,refresh,admin,export,convert,serve,search,reverse,lookup,details,status} ...
 .SH DESCRIPTION
     Command\-line tools for importing, updating, administrating and
 .br
@@ -12,6 +12,9 @@ nominatim
     
 .SH OPTIONS
 
+.TP
+\fB\-\-version\fR
+Print Nominatim version and exit
 
 .SS
 \fBSub-commands\fR
@@ -41,7 +44,10 @@ nominatim
     Analyse and maintain the database.
 .TP
 \fBnominatim\fR \fI\,export\/\fR
-    Export addresses as CSV file from the database.
+    Export places as CSV file from the database.
+.TP
+\fBnominatim\fR \fI\,convert\/\fR
+ Convert an existing database into a different format. (EXPERIMENTAL)
 .TP
 \fBnominatim\fR \fI\,serve\/\fR
     Start a simple web server for serving the API.
@@ -59,13 +65,15 @@ nominatim
     Execute API details query.
 .TP
 \fBnominatim\fR \fI\,status\/\fR
-    Execute API status query.
+
 .SH OPTIONS 'nominatim import'
 usage: nominatim import [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
-                        (--osm-file FILE | --continue {load-data,indexing,db-postprocess})
+                        [--osm-file FILE]
+                        [--continue {import-from-file,load-data,indexing,db-postprocess}]
                         [--osm2pgsql-cache SIZE] [--reverse-only]
-                        [--no-partitions] [--no-updates] [--ignore-errors]
-                        [--index-noanalyse]
+                        [--no-partitions] [--no-updates] [--offline]
+                        [--ignore-errors] [--index-noanalyse]
+                        [--prepare-database]
 
     Create a new Nominatim database from an OSM file.
 .br
@@ -102,7 +110,7 @@ Number of parallel threads to use
 OSM file to be imported (repeat for importing multiple files)
 
 .TP
-\fB\-\-continue\fR {load\-data,indexing,db\-postprocess}
+\fB\-\-continue\fR {import\-from\-file,load\-data,indexing,db\-postprocess}
 Continue an import that was interrupted
 
 .TP
@@ -121,6 +129,10 @@ Do not partition search indices (speeds up import of single country extracts)
 \fB\-\-no\-updates\fR
 Do not keep tables that are only needed for updating the database later
 
+.TP
+\fB\-\-offline\fR
+Do not attempt to load any additional data from the internet
+
 .TP
 \fB\-\-ignore\-errors\fR
 Continue import even when errors in SQL are present
@@ -129,6 +141,10 @@ Continue import even when errors in SQL are present
 \fB\-\-index\-noanalyse\fR
 Do not perform analyse operations during index (expert only)
 
+.TP
+\fB\-\-prepare\-database\fR
+Create the database but do not import any data
+
 .SH OPTIONS 'nominatim freeze'
 usage: nominatim freeze [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
 
@@ -171,8 +187,8 @@ Number of parallel threads to use
 .SH OPTIONS 'nominatim replication'
 usage: nominatim replication [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
                              [--init] [--no-update-functions]
-                             [--check-for-updates] [--once] [--no-index]
-                             [--osm2pgsql-cache SIZE]
+                             [--check-for-updates] [--once] [--catch-up]
+                             [--no-index] [--osm2pgsql-cache SIZE]
                              [--socket-timeout SOCKET_TIMEOUT]
 
     Update the database using an online replication service.
@@ -229,7 +245,7 @@ Initialise the update process
 
 .TP
 \fB\-\-no\-update\-functions\fR
-Do not update the trigger function to support differential updates.
+Do not update the trigger function to support differential updates (EXPERT)
 
 .TP
 \fB\-\-check\-for\-updates\fR
@@ -239,6 +255,10 @@ Check if new updates are available and exit
 \fB\-\-once\fR
 Download and apply updates only once. When not set, updates are continuously applied
 
+.TP
+\fB\-\-catch\-up\fR
+Download and apply updates until no new data is available on the server
+
 .TP
 \fB\-\-no\-index\fR
 Do not index the new data. Only usable together with \-\-once
@@ -290,6 +310,20 @@ usage: nominatim special-phrases [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
 .br
     'test/testdb/full_en_phrases_test.csv'.
 .br
+
+.br
+    The import can be further configured to ignore specific key/value pairs.
+.br
+    This is particularly useful when importing phrases from the wiki. The
+.br
+    default configuration excludes some very common tags like building=yes.
+.br
+    The configuration can be customized by putting a file `phrase\-settings.json`
+.br
+    with custom rules into the project directory or by using the `\-\-config`
+.br
+    option to point to another configuration file.
+.br
     
 
 
@@ -350,7 +384,7 @@ usage: nominatim add-data [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
 .br
     data. See the online documentation at
 .br
-    https://nominatim.org/release\-docs/latest/admin/Import/#installing\-tiger\-housenumber\-data\-for\-the\-us
+    https://nominatim.org/release\-docs/latest/customize/Tiger/
 .br
     for more information.
 .br
@@ -465,10 +499,11 @@ Maximum/finishing rank
 
 .SH OPTIONS 'nominatim refresh'
 usage: nominatim refresh [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
-                         [--postcodes] [--word-counts] [--address-levels]
-                         [--functions] [--wiki-data] [--importance]
-                         [--website] [--no-diff-updates]
-                         [--enable-debug-statements]
+                         [--postcodes] [--word-tokens] [--word-counts]
+                         [--address-levels] [--functions] [--wiki-data]
+                         [--secondary-importance] [--importance] [--website]
+                         [--data-object OBJECT] [--data-area OBJECT]
+                         [--no-diff-updates] [--enable-debug-statements]
 
     Recompute auxiliary data used by the indexing process.
 .br
@@ -512,6 +547,10 @@ Number of parallel threads to use
 \fB\-\-postcodes\fR
 Update postcode centroid table
 
+.TP
+\fB\-\-word\-tokens\fR
+Clean up search terms
+
 .TP
 \fB\-\-word\-counts\fR
 Compute frequency of full\-word search terms
@@ -528,6 +567,10 @@ Update the PL/pgSQL functions in the database
 \fB\-\-wiki\-data\fR
 Update Wikipedia/data importance numbers
 
+.TP
+\fB\-\-secondary\-importance\fR
+Update secondary importance raster data
+
 .TP
 \fB\-\-importance\fR
 Recompute place importances (expensive!)
@@ -536,6 +579,14 @@ Recompute place importances (expensive!)
 \fB\-\-website\fR
 Refresh the directory that serves the scripts for the web API
 
+.TP
+\fB\-\-data\-object\fR OBJECT
+Mark the given OSM object as requiring an update (format: [NWR]<id>)
+
+.TP
+\fB\-\-data\-area\fR OBJECT
+Mark the area around the given OSM object as requiring an update (format: [NWR]<id>)
+
 .TP
 \fB\-\-no\-diff\-updates\fR
 Do not enable code for propagating updates
@@ -546,7 +597,7 @@ Enable debug warning statements in functions
 
 .SH OPTIONS 'nominatim admin'
 usage: nominatim admin [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
-                       (--warm | --check-database | --migrate | --analyse-indexing)
+                       (--warm | --check-database | --migrate | --analyse-indexing | --collect-os-info | --clean-deleted AGE)
                        [--search-only] [--reverse-only]
                        [--osm-id OSM_ID | --place-id PLACE_ID]
 
@@ -588,6 +639,14 @@ Migrate the database to a new software version
 \fB\-\-analyse\-indexing\fR
 Print performance analysis of the indexing process
 
+.TP
+\fB\-\-collect\-os\-info\fR
+Generate a report about the host system information
+
+.TP
+\fB\-\-clean\-deleted\fR AGE
+Clean up deleted relations
+
 .TP
 \fB\-\-search\-only\fR
 Only pre\-warm tables for search queries
@@ -606,14 +665,17 @@ Analyse indexing of the given Nominatim object
 
 .SH OPTIONS 'nominatim export'
 usage: nominatim export [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
-                        [--output-type {continent,country,state,county,city,suburb,street,path}]
-                        [--output-format OUTPUT_FORMAT]
-                        [--output-all-postcodes] [--language LANGUAGE]
+                        [--output-type {country,state,county,city,suburb,street,path}]
+                        [--output-format OUTPUT_FORMAT] [--language LANGUAGE]
                         [--restrict-to-country COUNTRY_CODE]
                         [--restrict-to-osm-node ID] [--restrict-to-osm-way ID]
                         [--restrict-to-osm-relation ID]
 
-    Export addresses as CSV file from the database.
+    Export places as CSV file from the database.
+.br
+
+.br
+
 .br
     
 
@@ -636,16 +698,12 @@ Base directory of the Nominatim installation (default:.)
 Number of parallel threads to use
 
 .TP
-\fB\-\-output\-type\fR {continent,country,state,county,city,suburb,street,path}
+\fB\-\-output\-type\fR {country,state,county,city,suburb,street,path}
 Type of places to output (default: street)
 
 .TP
 \fB\-\-output\-format\fR \fI\,OUTPUT_FORMAT\/\fR
-Semicolon\-separated list of address types (see \-\-output\-type). Multiple ranks can be merged into one column by simply using a comma\-separated list.
-
-.TP
-\fB\-\-output\-all\-postcodes\fR
-List all postcodes for address instead of just the most likely one
+Semicolon\-separated list of address types (see \-\-output\-type). Additionally accepts:placeid,postcode
 
 .TP
 \fB\-\-language\fR \fI\,LANGUAGE\/\fR
@@ -667,21 +725,85 @@ Export only children of this OSM way
 \fB\-\-restrict\-to\-osm\-relation\fR ID
 Export only children of this OSM relation
 
+.SH OPTIONS 'nominatim convert'
+usage: nominatim convert [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                         [--format {sqlite}] --output OUTPUT [--with-reverse]
+                         [--with-search] [--with-details]
+
+ Convert an existing database into a different format. (EXPERIMENTAL)
+.br
+
+.br
+        Dump a read\-only version of the database in a different format.
+.br
+        At the moment only a SQLite database suitable for reverse lookup
+.br
+        can be created.
+.br
+    
+
+
+.TP
+\fB\-\-format\fR {sqlite}
+Format of the output database (must be sqlite currently)
+
+.TP
+\fB\-\-output\fR \fI\,OUTPUT\/\fR, \fB\-o\fR \fI\,OUTPUT\/\fR
+File to write the database to.
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-with\-reverse\fR, \fB\-\-without\-reverse\fR
+Enable/disable support for reverse and lookup API (default: enabled)
+
+.TP
+\fB\-\-with\-search\fR, \fB\-\-without\-search\fR
+Enable/disable support for search API (default: disabled)
+
+.TP
+\fB\-\-with\-details\fR, \fB\-\-without\-details\fR
+Enable/disable support for details API (default: enabled)
+
 .SH OPTIONS 'nominatim serve'
 usage: nominatim serve [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
-                       [--server SERVER]
+                       [--server SERVER] [--engine {php,falcon,starlette}]
 
     Start a simple web server for serving the API.
 .br
 
 .br
-    This command starts the built\-in PHP webserver to serve the website
+    This command starts a built\-in webserver to serve the website
 .br
     from the current project directory. This webserver is only suitable
 .br
     for testing and development. Do not use it in production setups!
 .br
 
+.br
+    There are different webservers available. The default 'php' engine
+.br
+    runs the classic PHP frontend. The other engines are Python servers
+.br
+    which run the new Python frontend code. This is highly experimental
+.br
+    at the moment and may not include the full API.
+.br
+
 .br
     By the default, the webserver can be accessed at: http://127.0.0.1:8088
 .br
@@ -709,12 +831,16 @@ Number of parallel threads to use
 \fB\-\-server\fR \fI\,SERVER\/\fR
 The address the server will listen to.
 
+.TP
+\fB\-\-engine\fR {php,falcon,starlette}
+Webserver framework to run. (default: falcon)
+
 .SH OPTIONS 'nominatim search'
 usage: nominatim search [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
-                        [--query QUERY] [--street STREET] [--city CITY]
-                        [--county COUNTY] [--state STATE] [--country COUNTRY]
-                        [--postalcode POSTALCODE]
-                        [--format {xml,json,jsonv2,geojson,geocodejson}]
+                        [--query QUERY] [--amenity AMENITY] [--street STREET]
+                        [--city CITY] [--county COUNTY] [--state STATE]
+                        [--country COUNTRY] [--postalcode POSTALCODE]
+                        [--format {xml,geojson,geocodejson,json,jsonv2,debug}]
                         [--addressdetails] [--extratags] [--namedetails]
                         [--lang LANGS]
                         [--polygon-output {geojson,kml,svg,text}]
@@ -758,6 +884,10 @@ Number of parallel threads to use
 \fB\-\-query\fR \fI\,QUERY\/\fR
 Free\-form query string
 
+.TP
+\fB\-\-amenity\fR \fI\,AMENITY\/\fR
+Structured query: name and/or type of POI
+
 .TP
 \fB\-\-street\fR \fI\,STREET\/\fR
 Structured query: housenumber and street
@@ -783,7 +913,7 @@ Structured query: country
 Structured query: postcode
 
 .TP
-\fB\-\-format\fR {xml,json,jsonv2,geojson,geocodejson}
+\fB\-\-format\fR {xml,geojson,geocodejson,json,jsonv2,debug}
 Format of result
 
 .TP
@@ -836,8 +966,8 @@ Do not remove duplicates from the result list
 
 .SH OPTIONS 'nominatim reverse'
 usage: nominatim reverse [-h] [-q] [-v] [--project-dir DIR] [-j NUM] --lat LAT
-                         --lon LON [--zoom ZOOM]
-                         [--format {xml,json,jsonv2,geojson,geocodejson}]
+                         --lon LON [--zoom ZOOM] [--layer LAYER]
+                         [--format {xml,geojson,geocodejson,json,jsonv2,debug}]
                          [--addressdetails] [--extratags] [--namedetails]
                          [--lang LANGS]
                          [--polygon-output {geojson,kml,svg,text}]
@@ -888,7 +1018,11 @@ Longitude of coordinate to look up (in WGS84)
 Level of detail required for the address
 
 .TP
-\fB\-\-format\fR {xml,json,jsonv2,geojson,geocodejson}
+\fB\-\-layer\fR LAYER
+OSM id to lookup in format <NRW><id> (may be repeated)
+
+.TP
+\fB\-\-format\fR {xml,geojson,geocodejson,json,jsonv2,debug}
 Format of result
 
 .TP
@@ -917,7 +1051,7 @@ Simplify output geometry.Parameter is difference tolerance in degrees.
 
 .SH OPTIONS 'nominatim lookup'
 usage: nominatim lookup [-h] [-q] [-v] [--project-dir DIR] [-j NUM] --id OSMID
-                        [--format {xml,json,jsonv2,geojson,geocodejson}]
+                        [--format {xml,geojson,geocodejson,json,jsonv2,debug}]
                         [--addressdetails] [--extratags] [--namedetails]
                         [--lang LANGS]
                         [--polygon-output {geojson,kml,svg,text}]
@@ -960,7 +1094,7 @@ Number of parallel threads to use
 OSM id to lookup in format <NRW><id> (may be repeated)
 
 .TP
-\fB\-\-format\fR {xml,json,jsonv2,geojson,geocodejson}
+\fB\-\-format\fR {xml,geojson,geocodejson,json,jsonv2,debug}
 Format of result
 
 .TP

diff --git a/docs/mkdocs.yml b/mkdocs.yml
similarity index 90%
rename from docs/mkdocs.yml
rename to mkdocs.yml
index fa65a11b97874ccbe001e8edc20b41846cccf840..6c2e3ac836194b2136289825d74841587d957977 100644 (file)
--- 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,18 @@ markdown_extensions:
     - toc:
         permalink: 
 extra_css: [extra.css, styles.css]
+exclude_docs: |
+    mk_install_instructions.py
+site_dir: site-html
 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

diff --git a/src/nominatim_api/core.py b/src/nominatim_api/core.py
index c460d98c3ce099817138e30d3dfc646ff9235905..6c4c37d7e824b681e91f3de6ace74968cc440813 100644 (file)
--- a/src/nominatim_api/core.py
+++ b/src/nominatim_api/core.py
@@ -382,7 +382,7 @@ class NominatimAPI:
 
     @property
     def config(self) -> Configuration:
-        """ Provide read-only access to the [configuration](#Configuration)
+        """ Provide read-only access to the [configuration](Configuration.md)
             used by the API.
         """
         return self._async_api.config

diff --git a/src/nominatim_api/results.py b/src/nominatim_api/results.py
index 805527a7b590ba9b80c1315536fc125abd6c9051..28c0fc1a4bf4a3d2e747d30c0d6032ea3ea0722e 100644 (file)
--- a/src/nominatim_api/results.py
+++ b/src/nominatim_api/results.py
@@ -127,7 +127,7 @@ class AddressLine:
 
     local_name: Optional[str] = None
     """ Place holder for localization of this address part. See
-        [Localization](#localization) below.
+        [Localization](Result-Handling.md#localization) below.
     """