preliminary library reference finished

docs/library/Getting-Started.md

@@ -9,20 +9,78 @@ also less constraints on the kinds of data that can be accessed. The library
 allows to get access to more detailed information about the objects saved
 in the database.
 
+!!! danger
+    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. Use is only recommended for advanced Python
+    programmers at the moment.
+
 ## 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.
 
-!!! warning
-    Access to the library is currently still experimental. 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.
+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.
+
+
+### 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
+search functions of Nominatim that are also knwon from its web API.
+
+This code snippet implements a simple search for the town if 'Brugge':
+
+=== "NominatimAPIAsync"
+    ```
+    from pathlib import Path
+    import asyncio
+
+    import nominatim.api as napi
+
+    async def search(query):
+        api = napi.NominatimAPIAsync(Path('.'))
+
+        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[1].centroid.y}')
+    ```
+
+=== "NominatimAPI"
+    ```
+    from pathlib import Path
+
+    import nominatim.api as napi
+
+    api = napi.NominatimAPI(Path('.'))
+
+    results = api.search('Brugge')
+
+    if not results:
+        print('Cannot find Brugge')
+    else:
+        print(f'Found a place at {results[0].centroid.x},{results[1].centroid.y}')
+    ```
+
+The Nonminatim API comes in two flavours: synchronous and asynchronous.
+The complete Nominatim library is written so that it can work asynchronously.
+If you have many requests to make, coroutines can speed up your applications
+significantly.
+
+For smaller scripts there is also a sychronous wrapper around the API.
+
+### Defining which database to use
+
 
-    A proper installation as a Python library will follow in the next
-    version.

docs/library/Input-Parameter-Types.md

@@ -49,8 +49,14 @@ types for place identification. All types are dataclasses.
 
 ## Layers
 
+Layers allow to restrict the search result to thematic groups. This is
+orthogonal to restriction by address ranks, which groups places by their
+geographic extent.
+
+
 ::: nominatim.api.DataLayer
     options:
         heading_level: 6
+        members_order: source
 
 

docs/library/Result-Handling.md

@@ -1,12 +1,47 @@
 # Result handling
 
+The search functions of the Nominatim API always return a result object that
+contains the full raw information about the place that is available in the
+database. This section discusses data types used in the results and utility
+functions that allow further processing of the results.
+
+## Result fields
+
+### Sources
+
+Nominatim takes the result data from multiple souces. The `source_table` field
+in the result describes, from which source the result was retrived.
+
 ::: nominatim.api.SourceTable
     options:
         heading_level: 6
+        members_order: source
+
+### Detailed address description
+
+When the `address_details` parameter is set, then functions return not
+only information about the result place but also about the place that
+make up the address. This information is almost always required, when you
+want to present the user with a human-readable description of the result.
+See also [Localization](#localization) below.
+
+The address details are available in the `address_rows` field as a ordered
+list of `AddressLine` objects with the country information last. The list also
+contains the result place itself and some artificial entries, for example,
+for the housenumber or the country code. This makes processing and creating
+a full address easiert.
 
 ::: nominatim.api.AddressLine
     options:
         heading_level: 6
+        members_order: source
+
+### Detailed search terms
+
+The `details` function can return detailed information about which search terms
+may be used to find a place, when the `keywords` parameter is set. Search
+terms are split into terms for the name of the place and search terms for
+its address.
 
 ::: nominatim.api.WordInfo
     options:

docs/mkdocs.yml

@@ -58,6 +58,7 @@ markdown_extensions:
     - codehilite
     - admonition
     - pymdownx.superfences
+    - pymdownx.tabbed
     - def_list
     - toc:
         permalink: 