enable CI tests for Ubuntu 24

[nominatim.git] / docs / library / Getting-Started.md

diff --git a/docs/library/Getting-Started.md b/docs/library/Getting-Started.md
index 88f25eb6ae47f7da198b075713de421c533336b1..22d9681d6fd119c42e67a5b605e47633a870e5ed 100644 (file)
--- a/docs/library/Getting-Started.md
+++ b/docs/library/Getting-Started.md
@@ -12,22 +12,18 @@ in the database.
     The library interface is currently in an experimental stage. There might
     be some smaller adjustments to the public interface until the next version.
 
-    The library also misses a proper installation routine, so some manipulation
-    of the PYTHONPATH is required. At the moment, use is only recommended for
-    developers wit some experience in Python.
-
 ## Installation
 
 To use the Nominatim library, you need access to a local Nominatim database.
-Follow the [installation and import instructions](../admin/) to set up your
-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.
+To install the package from the source tree directly, run:
+
+    pip install packaging/nominatim-api
 
-It is not yet possible to install it in the usual way via pip or inside a
-virtualenv. To get access to the library you need to set an appropriate
-PYTHONPATH. With the default installation, the python library can be found
-under `/usr/local/share/nominatim/lib-python`. If you have installed
-Nominatim under a different prefix, adapt the `/usr/local/` part accordingly.
-You can also point the PYTHONPATH to the Nominatim source code.
+Usually, you would want to run this in a virtual environment.
 
 ### A simple search example
 
@@ -35,7 +31,7 @@ To query the Nominatim database you need to first set up a connection. This
 is done by creating an Nominatim API object. This object exposes all the
 search functions of Nominatim that are also known from its web API.
 
-This code snippet implements a simple search for the town if 'Brugge':
+This code snippet implements a simple search for the town of 'Brugge':
 
 !!! example
     === "NominatimAPIAsync"
@@ -43,7 +39,7 @@ This code snippet implements a simple search for the town if 'Brugge':
         from pathlib import Path
         import asyncio
 
-        import nominatim.api as napi
+        import nominatim_api as napi
 
         async def search(query):
             api = napi.NominatimAPIAsync(Path('.'))
@@ -61,7 +57,7 @@ This code snippet implements a simple search for the town if 'Brugge':
         ``` python
         from pathlib import Path
 
-        import nominatim.api as napi
+        import nominatim_api as napi
 
         api = napi.NominatimAPI(Path('.'))
 
@@ -103,7 +99,7 @@ You should have set up this directory as part of the Nominatim import.
 Any configuration found in the `.env` file in this directory will automatically
 used.
 
-Yo may also configure Nominatim be setting environment variables.
+You may also configure Nominatim by setting environment variables.
 Normally, Nominatim will check the operating system environment. This can be
 overwritten by giving the constructor a dictionary of configuration parameters.
 
@@ -116,7 +112,7 @@ standard 'nominatim' database:
         from pathlib import Path
         import asyncio
 
-        import nominatim.api as napi
+        import nominatim_api as napi
 
         config_params = {
             'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium'
@@ -134,7 +130,7 @@ standard 'nominatim' database:
         ``` python
         from pathlib import Path
 
-        import nominatim.api as napi
+        import nominatim_api as napi
 
         config_params = {
             'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium'
@@ -161,7 +157,7 @@ Again searching for 'Brugge', this time with a nicely formatted result:
         from pathlib import Path
         import asyncio
 
-        import nominatim.api as napi
+        import nominatim_api as napi
 
         async def search(query):
             api = napi.NominatimAPIAsync(Path('.'))
@@ -180,7 +176,7 @@ Again searching for 'Brugge', this time with a nicely formatted result:
         ``` python
         from pathlib import Path
 
-        import nominatim.api as napi
+        import nominatim_api as napi
 
         api = napi.NominatimAPI(Path('.'))
 
@@ -219,7 +215,7 @@ creates a helper class that returns the name preferably in French. If that is
 not possible, it tries English and eventually falls back to the default `name`
 or `ref`.
 
-The Locale object can be applied to a name dictionary to return the best-matching
+The `Locale` object can be applied to a name dictionary to return the best-matching
 name out of it:
 
 ``` python