docs: improve contents listing

diff --git a/docs/api/Overview.md b/docs/api/Overview.md
index 383eef53650db44f68fb66272b0914319e232f98..aac57715178317c43a72e98fe45102bf271486e0 100644 (file)
--- a/docs/api/Overview.md
+++ b/docs/api/Overview.md
@@ -1,5 +1,3 @@
-### Nominatim API
-

 !!! Attention
     The current version of Nominatim implements two different search frontends:
     the old PHP frontend and the new Python frontend. They have a very similar
 !!! Attention
     The current version of Nominatim implements two different search frontends:
     the old PHP frontend and the new Python frontend. They have a very similar

diff --git a/docs/library/Configuration.md b/docs/library/Configuration.md
index e13470e9fceb5a0d5a45f26cd46d2c8d46e55b39..713d1c53a0fdbbfa3cd5ffcbd980ee601651f0e9 100644 (file)
--- a/docs/library/Configuration.md
+++ b/docs/library/Configuration.md
@@ -1,11 +1,13 @@
 # Configuration
 
 When using Nominatim through the library, it can be configured in exactly
 # Configuration
 
 When using Nominatim through the library, it can be configured in exactly

-the same way as when running as a service. This means that you should have
-created a [project directory](../admin/Import.md#creating-the-project-directory)
-which contains all files belonging to the Nominatim instance. It can also contain
-an `.env` file with configuration options. Setting configuration parameters
-via environment variables works as well.
+the same way as when running as a service. You may instantiate the library
+against the [project directory](../admin/Import.md#creating-the-project-directory)
+of your Nominatim installation. It contains all files belonging to the
+Nominatim instance. This may include an `.env` file with configuration options.
+Setting configuration parameters via environment variables works as well.
+Alternatively to using the operating system's environment, a set of
+configuration parameters may also be passed to the Nomiantim API object.

 
 Configuration options are resolved in the following order:
 
 
 Configuration options are resolved in the following order:
 

diff --git a/docs/library/Getting-Started.md b/docs/library/Getting-Started.md
index 6206022ff2bcafb0356287b55fcbe2169bbd55e3..9f81724a155888b4e8174935fce372112f8d193f 100644 (file)
--- a/docs/library/Getting-Started.md
+++ b/docs/library/Getting-Started.md
@@ -34,7 +34,7 @@ To install the package from the source tree directly, run:
 
 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
+## A simple search example

 
 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
 
 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


@@ -88,7 +88,7 @@ implementations. The documentation itself will usually refer only to
 available only for the synchronous or asynchronous version, this will be
 explicitly mentioned.
 
 available only for the synchronous or asynchronous version, this will be
 explicitly mentioned.
 

-### Defining which database to use
+## Defining which database to use

 
 The [Configuration](../admin/Import.md#configuration-setup-in-env)
 section explains how Nominatim is configured using the
 
 The [Configuration](../admin/Import.md#configuration-setup-in-env)
 section explains how Nominatim is configured using the


@@ -103,7 +103,41 @@ have normally created a [project directory](../admin/Import.md#creating-the-proj
 which stores the various configuration and customization files that Nominatim
 needs. You may pass the location of the project directory to your
 'Nominatim API class' constructor and it will read the .env file in the
 which stores the various configuration and customization files that Nominatim
 needs. You may pass the location of the project directory to your
 'Nominatim API class' constructor and it will read the .env file in the

-directory and set the configuration accordingly.
+directory and set the configuration accordingly. Here is the simple search
+example, using the configuration from a pre-defined project directory in
+`/srv/nominatim-project`:
+
+!!! example
+    === "NominatimAPIAsync"
+        ``` python
+        import asyncio
+
+        import nominatim_api as napi
+
+        async def search(query):
+            async with napi.NominatimAPIAsync('/srv/nominatim-project') as api:
+                return await api.search(query)
+
+        results = asyncio.run(search('Brugge'))
+        if not results:
+            print('Cannot find Brugge')
+        else:
+            print(f'Found a place at {results[0].centroid.x},{results[0].centroid.y}')
+        ```
+
+    === "NominatimAPI"
+        ``` python
+        import nominatim_api as napi
+
+        with napi.NominatimAPI('/srv/nominatim-project') as api:
+            results = api.search('Brugge')
+
+        if not results:
+            print('Cannot find Brugge')
+        else:
+            print(f'Found a place at {results[0].centroid.x},{results[0].centroid.y}')
+        ```
+

 
 You may also configure Nominatim by setting environment variables.
 Normally Nominatim will check the operating system environment. Lets
 
 You may also configure Nominatim by setting environment variables.
 Normally Nominatim will check the operating system environment. Lets


@@ -148,9 +182,10 @@ like this:
         ```
 
 When the `environ` parameter is given, then only configuration variables
         ```
 
 When the `environ` parameter is given, then only configuration variables

-from this dictionary will be used.
+from this dictionary will be used. The operating system's environment
+variables will be ignored.

 
 

-### Presenting results to humans
+## Presenting results to humans

 
 All search functions return full result objects from the database. Such a
 result object contains lots of details: names, address information, OSM tags etc.
 
 All search functions return full result objects from the database. Such a
 result object contains lots of details: names, address information, OSM tags etc.

diff --git a/docs/library/Low-Level-DB-Access.md b/docs/library/Low-Level-DB-Access.md
index 84a40b9b04a963f9f1a64a21a83b7ca219d5f047..9669906122f31fcbfae3b925dcdd0673cbcbf7bb 100644 (file)
--- a/docs/library/Low-Level-DB-Access.md
+++ b/docs/library/Low-Level-DB-Access.md
@@ -24,12 +24,11 @@ the placex table:
 
 ```
 import asyncio
 
 ```
 import asyncio

-from pathlib import Path

 import sqlalchemy as sa
 from nominatim_api import NominatimAPIAsync
 
 async def print_table_size():
 import sqlalchemy as sa
 from nominatim_api import NominatimAPIAsync
 
 async def print_table_size():

-    api = NominatimAPIAsync(Path('.'))
+    api = NominatimAPIAsync()

 
     async with api.begin() as conn:
         cnt = await conn.scalar(sa.select(sa.func.count()).select_from(conn.t.placex))
 
     async with api.begin() as conn:
         cnt = await conn.scalar(sa.select(sa.func.count()).select_from(conn.t.placex))

diff --git a/mkdocs.yml b/mkdocs.yml
index aa6e1aa0f5cd86e1925fb0a18ac2821263c173a1..b6fd0ec7f518149474ed78a4f6ebbaf20e79b74f 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -4,6 +4,7 @@ theme:
   name: material
   features:
     - navigation.tabs
   name: material
   features:
     - navigation.tabs

+    - toc.integrate

   plugins:
     - privacy
 copyright: Copyright © Nominatim developer community
   plugins:
     - privacy
 copyright: Copyright © Nominatim developer community


@@ -71,6 +72,7 @@ markdown_extensions:
         alternate_style: true
     - def_list
     - toc:
         alternate_style: true
     - def_list
     - toc:

+        toc_depth: 4

         permalink: 🔗
 extra_css: [extra.css, styles.css]
 exclude_docs: |
         permalink: 🔗
 extra_css: [extra.css, styles.css]
 exclude_docs: |