Added Manual page and fixed documentation

.github/actions/build-nominatim/action.yml

@@ -6,7 +6,7 @@ runs:
     steps:
         - name: Install prerequisites
           run: |
-            sudo apt-get install -y -qq libboost-system-dev libboost-filesystem-dev libexpat1-dev zlib1g-dev libbz2-dev libpq-dev libproj-dev libicu-dev python3-psycopg2 python3-pyosmium python3-dotenv python3-psutil python3-jinja2 python3-icu
+            sudo apt-get install -y -qq libboost-system-dev libboost-filesystem-dev libexpat1-dev zlib1g-dev libbz2-dev libpq-dev libproj-dev libicu-dev python3-psycopg2 python3-pyosmium python3-dotenv python3-psutil python3-jinja2 python3-icu python3-argparse-manpage
           shell: bash
 
         - name: Download dependencies

CMakeLists.txt

@@ -36,6 +36,7 @@ set(BUILD_API on CACHE BOOL "Build everything for the API server")
 set(BUILD_MODULE on CACHE BOOL "Build PostgreSQL module")
 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)")
 
 #-----------------------------------------------------------------------------
@@ -208,6 +209,14 @@ if (BUILD_DOCS)
    add_subdirectory(docs)
 endif()
 
+#-----------------------------------------------------------------------------
+# Manual page
+#-----------------------------------------------------------------------------
+
+if (BUILD_MANPAGE)
+   add_subdirectory(manual)
+endif()
+
 #-----------------------------------------------------------------------------
 # Installation
 #-----------------------------------------------------------------------------

manual/CMakeLists.txt

@@ -0,0 +1,15 @@
+# Creates and installs manual page
+
+execute_process(
+    COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/nominatim.1 ${CMAKE_CURRENT_BINARY_DIR}/nominatim.1
+)
+
+configure_file(${PROJECT_SOURCE_DIR}/manual/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 > nominatim.1
+)
+
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/nominatim.1 DESTINATION share/man/man1 )

manual/create-manpage.tmpl

@@ -0,0 +1,12 @@
+#!/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(phpcgi_path='@PHPCGI_BIN@')
+
+    return parser.parser

nominatim/cli.py

@@ -242,11 +242,10 @@ class AdminServe:
     def run(args):
         run_php_server(args.server, args.project_dir / 'website')
 
-
+def get_set_parser(**kwargs):
-def nominatim(**kwargs):
     """\
-    Command-line tools for importing, updating, administrating and
+    Initializes the parser and adds various subcommands for
-    querying the Nominatim database.
+    nominatim cli.
     """
     parser = CommandlineParser('nominatim', nominatim.__doc__)
 
@@ -276,4 +275,14 @@ def nominatim(**kwargs):
 
     parser.add_subcommand('transition', clicmd.AdminTransition)
 
+    return parser
+
+
+def nominatim(**kwargs):
+    """\
+    Command-line tools for importing, updating, administrating and
+    querying the Nominatim database.
+    """
+    parser = get_set_parser(**kwargs)
+
     return parser.run(**kwargs)

vagrant/Install-on-Centos-7.sh

@@ -42,7 +42,7 @@
                         python3-pip python3-setuptools python3-devel \
                         expat-devel zlib-devel libicu-dev
 
-    pip3 install --user psycopg2 python-dotenv psutil Jinja2 PyICU
+    pip3 install --user psycopg2 python-dotenv psutil Jinja2 PyICU argparse-manpage
 
 
 #

vagrant/Install-on-Centos-8.sh

@@ -35,7 +35,7 @@
                         python3-pip python3-setuptools python3-devel \
                         expat-devel zlib-devel libicu-dev
 
-    pip3 install --user psycopg2 python-dotenv psutil Jinja2 PyICU
+    pip3 install --user psycopg2 python-dotenv psutil Jinja2 PyICU argparse-manpage
 
 
 #

vagrant/Install-on-Ubuntu-18.sh

@@ -30,7 +30,8 @@ export DEBIAN_FRONTEND=noninteractive #DOCS:
                         postgresql-server-dev-10 postgresql-10-postgis-2.4 \
                         postgresql-contrib-10 postgresql-10-postgis-scripts \
                         php php-pgsql php-intl libicu-dev python3-pip \
-                        python3-psycopg2 python3-psutil python3-jinja2 python3-icu git
+                        python3-psycopg2 python3-psutil python3-jinja2 python3-icu git \
+                        python3-argparse-manpage
 
 # The python-dotenv package that comes with Ubuntu 18.04 is too old, so
 # install the latest version from pip:

vagrant/Install-on-Ubuntu-20.sh

@@ -33,7 +33,8 @@ export DEBIAN_FRONTEND=noninteractive #DOCS:
                         postgresql-server-dev-12 postgresql-12-postgis-3 \
                         postgresql-contrib-12 postgresql-12-postgis-3-scripts \
                         php php-pgsql php-intl libicu-dev python3-dotenv \
-                        python3-psycopg2 python3-psutil python3-jinja2 python3-icu git
+                        python3-psycopg2 python3-psutil python3-jinja2 python3-icu git \
+                        python3-argparse-manpage
 
 #
 # System Configuration