diff --git a/.gitignore b/.gitignore index 8e91f1e5cd..23bcdb1c6b 100644 --- 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 01a71a3c59..dd5c3110e3 100644 --- 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 dae45322a0..cd7280fe19 100644 --- 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 index 8f864ec303..0000000000 --- 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 821a2c06d9..9275bab86d 100644 --- 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 9159ac6266..cd561718ae 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/bash2md.sh b/docs/bash2md.sh deleted file mode 100755 index a62fbd1e21..0000000000 --- a/docs/bash2md.sh +++ /dev/null @@ -1,7 +0,0 @@ -#!/bin/sh -# -# Extract markdown-formatted documentation from a source file -# -# Usage: bash2md.sh - -sed '/^#!/d;s:^#\( \|$\)::;s/.*#DOCS://' $1 > $2 diff --git a/docs/customize/Tokenizers.md b/docs/customize/Tokenizers.md index 6b811a9adb..ee51fec05b 100644 --- a/docs/customize/Tokenizers.md +++ b/docs/customize/Tokenizers.md @@ -52,7 +52,7 @@ NOMINATIM_DATABASE_MODULE_PATH= ``` 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 19948e7cc2..1db32a6e3a 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/library/Input-Parameter-Types.md b/docs/library/Input-Parameter-Types.md index 5c53773290..d27bc96ff9 100644 --- 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 index 0000000000..f8edc89c29 --- /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 index 144b9f41aa..0000000000 --- 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 index 0000000000..94206c4f76 --- /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 index 427bcb63b1..0000000000 --- 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 22eed2c6e3..94fc989c26 100644 --- 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]) + +.TP +\fB\-\-data\-area\fR OBJECT +Mark the area around the given OSM object as requiring an update (format: [NWR]) + .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 (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 (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 fa65a11b97..6c2e3ac836 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,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 c460d98c3c..6c4c37d7e8 100644 --- a/src/nominatim_api/core.py +++ b/src/nominatim_api/core.py @@ -382,7 +382,7 @@ def close(self) -> None: @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 805527a7b5..28c0fc1a4b 100644 --- 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. """