From 474a22cb3bad908736748b3f8d3de7b5f36bba57 Mon Sep 17 00:00:00 2001 From: Sarah Hoffmann Date: Wed, 7 Aug 2024 16:38:56 +0200 Subject: [PATCH] build man page without CMake --- CMakeLists.txt | 9 -- Makefile | 6 +- man/CMakeLists.txt | 15 --- man/create-manpage.py | 12 +++ man/create-manpage.tmpl | 12 --- man/nominatim.1 | 210 ++++++++++++++++++++++++++++++++-------- 6 files changed, 189 insertions(+), 75 deletions(-) delete mode 100644 man/CMakeLists.txt create mode 100644 man/create-manpage.py delete mode 100644 man/create-manpage.tmpl diff --git a/CMakeLists.txt b/CMakeLists.txt index e52dc913..dd5c3110 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -46,7 +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_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") @@ -187,14 +186,6 @@ if (BUILD_MODULE) add_subdirectory(module) endif() -#----------------------------------------------------------------------------- -# Manual page -#----------------------------------------------------------------------------- - -if (BUILD_MANPAGE) - add_subdirectory(man) -endif() - #----------------------------------------------------------------------------- # Installation #----------------------------------------------------------------------------- diff --git a/Makefile b/Makefile index 29243583..cd7280fe 100644 --- a/Makefile +++ b/Makefile @@ -37,4 +37,8 @@ doc: serve-doc: mkdocs serve -.PHONY: tests mypy pytest lint bdd build clean-build build-db build-api doc serve-doc +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/man/CMakeLists.txt b/man/CMakeLists.txt deleted file mode 100644 index 144b9f41..00000000 --- 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 00000000..94206c4f --- /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 427bcb63..00000000 --- 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 22eed2c6..94fc989c 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