restructure library documentation

diff --git a/docs/index.md b/docs/index.md
index 0ed6c54652e42e48fb693635031f814b78417b6c..b60a6d203a6c2fbb38dd91d8c9b386c9aca9c70a 100644 (file)
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,10 +1,12 @@
 Nominatim (from the Latin, 'by name') is a tool to search OSM data by name and address and to generate synthetic addresses of OSM points (reverse geocoding).
 
 Nominatim (from the Latin, 'by name') is a tool to search OSM data by name and address and to generate synthetic addresses of OSM points (reverse geocoding).
 

-This guide comes in four parts:
+This guide comes in five parts:

 
  * __[API reference](api/Overview.md)__ for users of Nominatim
  * __[Administration Guide](admin/Installation.md)__ for those who want
    to install their own Nominatim server
  * __[Customization Guide](customize/Overview.md)__ for those who want to
    adapt their own installation to their special requirements
 
  * __[API reference](api/Overview.md)__ for users of Nominatim
  * __[Administration Guide](admin/Installation.md)__ for those who want
    to install their own Nominatim server
  * __[Customization Guide](customize/Overview.md)__ for those who want to
    adapt their own installation to their special requirements

+ * __[Library Guide](library/Getting-Started.md)__ for Python developers who
+   want to use Nominatim as a library in their project

  * __[Developer's Guide](develop/overview.md)__ for developers of the software
  * __[Developer's Guide](develop/overview.md)__ for developers of the software

diff --git a/docs/library/Configuration.md b/docs/library/Configuration.md
new file mode 100644 (file)
index 0000000..19b8feb
--- /dev/null
+++ b/docs/library/Configuration.md
@@ -0,0 +1,11 @@
+# Configuration class
+
+::: nominatim.config.Configuration
+    options:
+        members:
+            - get_bool
+            - get_int
+            - get_str_list
+            - get_path
+        heading_level: 6
+        show_signature_annotations: True

diff --git a/docs/library/Getting-Started.md b/docs/library/Getting-Started.md
new file mode 100644 (file)
index 0000000..38517b1
--- /dev/null
+++ b/docs/library/Getting-Started.md
@@ -0,0 +1,28 @@
+# Getting Started
+
+The Nominatim search frontend can directly be used as a Python library in
+scripts and applications. When you have imported your own Nominatim database,
+then it is no longer necessary to run a full web service for it and access
+the database through http requests. With the Nominatim library it is possible
+to access all search functionality directly from your Python code. There are
+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.
+
+## 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.
+
+    A proper installation as a Python library will follow in the next
+    version.

diff --git a/docs/library/Input-Parameter-Types.md b/docs/library/Input-Parameter-Types.md
new file mode 100644 (file)
index 0000000..e6b5138
--- /dev/null
+++ b/docs/library/Input-Parameter-Types.md
@@ -0,0 +1,33 @@
+# Input parameters
+
+## Place identification
+
+::: nominatim.api.PlaceID
+    options:
+        heading_level: 6
+
+::: nominatim.api.OsmID
+    options:
+        heading_level: 6
+
+## Geometries
+
+::: nominatim.api.GeometryFormat
+    options:
+        heading_level: 6
+
+::: nominatim.api.Point
+    options:
+        heading_level: 6
+
+::: nominatim.api.Bbox
+    options:
+        heading_level: 6
+
+## Layers
+
+::: nominatim.api.DataLayer
+    options:
+        heading_level: 6
+
+

diff --git a/docs/library/Introduction.md b/docs/library/Introduction.md
new file mode 100644 (file)
index 0000000..3700bca
--- /dev/null
+++ b/docs/library/Introduction.md
@@ -0,0 +1,12 @@
+# Nominatim Frontend as a Library
+
+The Nominatim search frontend can directly be used as a Python library in
+scripts and applications. When you have imported your own Nominatim database,
+then it is no longer necessary to run a full web service for it and access
+the database through http requests. With the Nominatim library it is possible
+to access all search functionality directly from your Python code. There are
+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.
+
+

diff --git a/docs/library/Low-Level-DB-Access.md b/docs/library/Low-Level-DB-Access.md
new file mode 100644 (file)
index 0000000..371989e
--- /dev/null
+++ b/docs/library/Low-Level-DB-Access.md
@@ -0,0 +1,5 @@
+# Low-level connections
+
+::: nominatim.api.SearchConnection
+    options:
+        heading_level: 6

diff --git a/docs/library/NominatimAPI.md b/docs/library/NominatimAPI.md
new file mode 100644 (file)
index 0000000..a5481a1
--- /dev/null
+++ b/docs/library/NominatimAPI.md
@@ -0,0 +1,38 @@
+# The Nominatim API classes
+
+The API classes are the core object of the search library. Always instantiate
+one of these classes first. The API classes are **not threadsafe**. You need
+to instantiate a separate instance for each thread.
+
+### NominatimAPI
+
+::: nominatim.api.NominatimAPI
+    options:
+        members:
+            - __init__
+            - config
+            - close
+            - status
+            - details
+            - lookup
+            - reverse
+            - search
+            - search_address
+            - search_category
+        heading_level: 6
+        group_by_category: False
+        show_signature_annotations: True
+
+
+### NominatimAPIAsync
+
+::: nominatim.api.NominatimAPIAsync
+    options:
+        members:
+            - __init__
+            - setup_database
+            - close
+            - begin
+        heading_level: 6
+        group_by_category: False
+        show_signature_annotations: True

diff --git a/docs/library/Result-Handling.md b/docs/library/Result-Handling.md
new file mode 100644 (file)
index 0000000..8c9972b
--- /dev/null
+++ b/docs/library/Result-Handling.md
@@ -0,0 +1,19 @@
+# Result handling
+
+::: nominatim.api.SourceTable
+    options:
+        heading_level: 6
+
+::: nominatim.api.AddressLine
+    options:
+        heading_level: 6
+
+::: nominatim.api.WordInfo
+    options:
+        heading_level: 6
+
+## Localization
+
+::: nominatim.api.Locales
+    options:
+        heading_level: 6

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index fd1995ab55b75402ffc7c3a3dc9afead7e9a498c..c3af00bd8d03c54c046933124f7c8f744e6e5bb7 100644 (file)
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -36,9 +36,12 @@ nav:
         - 'External data: US housenumbers from TIGER': 'customize/Tiger.md'
         - 'External data: Postcodes': 'customize/Postcodes.md'
     - 'Library Guide':
         - 'External data: US housenumbers from TIGER': 'customize/Tiger.md'
         - 'External data: Postcodes': 'customize/Postcodes.md'
     - 'Library Guide':

-        - 'Introduction': 'library/Introduction.md'

         - 'Getting Started': 'library/Getting-Started.md'
         - 'Getting Started': 'library/Getting-Started.md'

-        - 'Reference': 'library/Reference.md'
+        - 'Nominatim API class': 'library/NominatimAPI.md'
+        - 'Configuration': 'library/Configuration.md'
+        - 'Input Parameter Types': 'library/Input-Parameter-Types.md'
+        - 'Result Handling': 'library/Result-Handling.md'
+        - 'Low-level DB Access': 'library/Low-Level-DB-Access.md'

     - 'Developers Guide':
         - 'Architecture Overview' : 'develop/overview.md'
         - 'Database Layout' : 'develop/Database-Layout.md'
     - 'Developers Guide':
         - 'Architecture Overview' : 'develop/overview.md'
         - 'Database Layout' : 'develop/Database-Layout.md'