From ecf4693a799055b3795ca691337941f931cf0a59 Mon Sep 17 00:00:00 2001 From: Sarah Hoffmann Date: Sat, 29 Jun 2024 16:27:26 +0200 Subject: [PATCH] improve wording as per review --- docs/admin/Migration.md | 2 +- docs/develop/Development-Environment.md | 21 ++++++++++++++------- docs/library/Getting-Started.md | 4 ++-- packaging/nominatim-api/README.md | 10 +++++----- packaging/nominatim-api/pyproject.toml | 2 ++ packaging/nominatim-db/README.md | 19 +++++++++++-------- packaging/nominatim-db/pyproject.toml | 3 ++- vagrant/Install-on-Ubuntu-24.sh | 14 ++++++++------ 8 files changed, 45 insertions(+), 30 deletions(-) diff --git a/docs/admin/Migration.md b/docs/admin/Migration.md index 59702e7bb..e4db38d15 100644 --- a/docs/admin/Migration.md +++ b/docs/admin/Migration.md @@ -19,7 +19,7 @@ breaking changes. **Please read them before running the migration.** ### New structure for Python packages -The nominatim Python package has been split into nominatim-db and nominatim-api. +The nominatim Python package has been split into `nominatim-db` and `nominatim-api`. Any imports need to be adapted accordingly. If you are running the Python frontend, change the server module from diff --git a/docs/develop/Development-Environment.md b/docs/develop/Development-Environment.md index 20d024114..b3c816118 100644 --- a/docs/develop/Development-Environment.md +++ b/docs/develop/Development-Environment.md @@ -4,7 +4,7 @@ This chapter gives an overview how to set up Nominatim for development and how to run tests. !!! Important - This guide assumes that you develop under the latest version of Debain/Ubuntu. + This guide assumes you develop under the latest version of Debian/Ubuntu. You can of course also use your favourite distribution. You just might have to adapt the commands below slightly, in particular the commands for installing additional software. @@ -41,8 +41,8 @@ It has the following additional requirements: For testing the Python search frontend, you need to install extra dependencies depending on your choice of webserver framework: -* [httpx](https://www.python-httpx.org/) (starlette only) -* [asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan) (starlette only) +* [httpx](https://www.python-httpx.org/) (Starlette only) +* [asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan) (Starlette only) The documentation is built with mkdocs: @@ -106,12 +106,12 @@ be run in-place. The source directory features a special script but executes against the code in the source tree. For example: ``` -me@machine:~$ cd Nomiantim -me@machine:~Nomiantim$ ./nominatim-cli.py --version +me@machine:~$ cd Nominatim +me@machine:~Nominatim$ ./nominatim-cli.py --version Nominatim version 4.4.99-1 ``` -Make sure you have activated the virtual environment that holds all +Make sure you have activated the virtual environment holding all necessary dependencies. ## Executing Tests @@ -124,7 +124,14 @@ To run all tests, run make from the source root: make tests ``` -There are also goals for executing parts of the test suite: mypy, lint, pytest, bdd. +There are also make targets for executing only parts of the test suite. +For example to run linting only use: + +```sh +make lint +``` + +The possible testing targets are: mypy, lint, pytest, bdd. For more information about the structure of the tests and how to change and extend the test suite, see the [Testing chapter](Testing.md). diff --git a/docs/library/Getting-Started.md b/docs/library/Getting-Started.md index 22d9681d6..1f5b2baa5 100644 --- a/docs/library/Getting-Started.md +++ b/docs/library/Getting-Started.md @@ -18,12 +18,12 @@ To use the Nominatim library, you need access to a local Nominatim database. Follow the [installation](../admin/Installation.md) and [import](../admin/Import.md) instructions to set up your database. -The Nominatim frontend library is contained in the 'nominatim-api' package. +The Nominatim frontend library is contained in the Python package `nominatim-api`. To install the package from the source tree directly, run: pip install packaging/nominatim-api -Usually, you would want to run this in a virtual environment. +Usually you would want to run this in a virtual environment. ### A simple search example diff --git a/packaging/nominatim-api/README.md b/packaging/nominatim-api/README.md index a0d43ade0..9dddbdc2f 100644 --- a/packaging/nominatim-api/README.md +++ b/packaging/nominatim-api/README.md @@ -4,8 +4,8 @@ Nominatim is a tool to search OpenStreetMap data by name and address (geocoding) and to generate synthetic addresses of OSM points (reverse geocoding). -This module implements the library for searching in a Nominatim database -imported with the 'nominatim-db' package. +This module implements the library for searching a Nominatim database +imported with the [`nominatim-db`](https://pypi.org/project/nominatim-db/) package. ## Installation @@ -15,7 +15,7 @@ To install the Nominatim API from pypi, run: ## Running a Nominatim server -You need falcon or starlette to run Nominatim as a service, as well as +You need Falcon or Starlette to run Nominatim as a service, as well as an ASGI-capable server like uvicorn. To install them from pypi run: pip install falcon uvicorn @@ -28,10 +28,10 @@ package. Go to the project directory, then run uvicorn as: ## Documentation The full documentation for the Nominatim library can be found at: -https://nominatim.org/release-docs/develop/library/Getting-Started/ +https://nominatim.org/release-docs/latest/library/Getting-Started/ The v1 API of the server is documented at: -https://nominatim.org/release-docs/develop/api/Overview/ +https://nominatim.org/release-docs/latest/api/Overview/ ## License diff --git a/packaging/nominatim-api/pyproject.toml b/packaging/nominatim-api/pyproject.toml index 4b268b165..9d5f79858 100644 --- a/packaging/nominatim-api/pyproject.toml +++ b/packaging/nominatim-api/pyproject.toml @@ -24,7 +24,9 @@ dynamic = ["version"] [project.urls] Homepage = "https://nominatim.org" +Documentation = "https://nominatim.org/release-docs/latest/" Issues = "https://github.com/osm-search/Nominatim/issues" +Repository = "https://github.com/osm-search/Nominatim" [build-system] requires = ["hatchling"] diff --git a/packaging/nominatim-db/README.md b/packaging/nominatim-db/README.md index dad12886f..a8ffd09a3 100644 --- a/packaging/nominatim-db/README.md +++ b/packaging/nominatim-db/README.md @@ -12,9 +12,9 @@ command-line tool for importing and maintaining the database. ### Prerequisites Nominatim requires [osm2pgsql](https://osm2pgsql.org/) (>=1.8) for reading -OSM data and [PostgreSQL](https://www.postgresql.org/) to store the data. +OSM data and [PostgreSQL](https://www.postgresql.org/) (>=9.6) to store the data. -On Ubuntu (>=23.04) and Debian (using backports), you can install them with: +On Ubuntu (>=23.04) and Debian (when using backports), you can install them with: sudo apt-get install osm2pgsql postgresql-postgis @@ -30,21 +30,24 @@ To install Nominatim from pypi, run: First create a project directory for your new Nominatim database, which is the space for additional configuration and customization: - mkdir planet-project + mkdir nominatim-project + +Make sure you run all nominatim commands from within the project directory: + + cd nominatim-project Download an appropriate data extract, for example from [Geofabrik](https://download.geofabrik.de/) and import the file: nominatim import --osm-file -You will need to install the 'nominatim-api' package to query the -database. +You will need to install the [`nominatim-api`](https://pypi.org/project/nominatim-api/) +package to query the database. ## Documentation -The documentation of the latest development version is in the -`docs/` subdirectory. A HTML version can be found at -https://nominatim.org/release-docs/develop/ . +A HTML version of the documentation can be found at +https://nominatim.org/release-docs/latest/ . ## License diff --git a/packaging/nominatim-db/pyproject.toml b/packaging/nominatim-db/pyproject.toml index 69b863c2a..11018b1ef 100644 --- a/packaging/nominatim-db/pyproject.toml +++ b/packaging/nominatim-db/pyproject.toml @@ -26,8 +26,9 @@ dynamic = ["version"] [project.urls] Homepage = "https://nominatim.org" -Issues = "https://github.com/osm-search/Nominatim/issues" Documentation = "https://nominatim.org/release-docs/latest/" +Issues = "https://github.com/osm-search/Nominatim/issues" +Repository = "https://github.com/osm-search/Nominatim" [build-system] requires = ["hatchling"] diff --git a/vagrant/Install-on-Ubuntu-24.sh b/vagrant/Install-on-Ubuntu-24.sh index 05dc38a4c..69dc481b8 100755 --- a/vagrant/Install-on-Ubuntu-24.sh +++ b/vagrant/Install-on-Ubuntu-24.sh @@ -67,7 +67,7 @@ fi #DOCS: # --------------------- # # Tune the postgresql configuration, which is located in -# `/etc/postgresql/14/main/postgresql.conf`. See section *Tuning the PostgreSQL database* +# `/etc/postgresql/16/main/postgresql.conf`. See section *Tuning the PostgreSQL database* # in [the installation page](../admin/Installation.md#tuning-the-postgresql-database) # for the parameters to change. # @@ -124,9 +124,11 @@ fi #DOCS: # Nominatim is now ready to use. The nominatim binary is available at # `$USERHOME/venv/bin/nominatim`. If you want to have 'nominatim' in your # path, simply activate the virtual environment: - - - +# +#DOCS:```sh +# . $USERHOME/nominatim-venv/bin/activate +#DOCS:``` +# # You can continue with # [importing a database from OSM data](../admin/Import.md). If you want to set up # the API frontend first, continue reading. @@ -135,8 +137,8 @@ fi #DOCS: # ============================== # # The Python frontend is contained in the nominatim-api package. To run -# the API as a webservice, you also need falcon with uvicorn/gunicorn to -# serve the API. +# the API as a webservice, you also need falcon with uvicorn to serve the API. +# It is generally recommended to run falcon/uvicorn on top of gunicorn. # # To install all packages, run: