From: Sarah Hoffmann Date: Tue, 22 Aug 2023 19:46:10 +0000 (+0200) Subject: restructure library documentation X-Git-Tag: v4.3.0~13^2~11 X-Git-Url: https://git.openstreetmap.org./nominatim.git/commitdiff_plain/309ac46b989b19b7a613e5031c5b2dde231b7cd6 restructure library documentation --- diff --git a/docs/index.md b/docs/index.md index 0ed6c546..b60a6d20 100644 --- 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). -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 + * __[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 diff --git a/docs/library/Configuration.md b/docs/library/Configuration.md new file mode 100644 index 00000000..19b8feb8 --- /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 index 00000000..38517b14 --- /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 index 00000000..e6b5138c --- /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 index 00000000..3700bca2 --- /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 index 00000000..371989eb --- /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 index 00000000..a5481a19 --- /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 index 00000000..8c9972b6 --- /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 fd1995ab..c3af00bd 100644 --- 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': - - 'Introduction': 'library/Introduction.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'