From ae7226e12d0386549f0bd609046e75d73a44c50c Mon Sep 17 00:00:00 2001
From: Sarah Hoffmann <lonvia@denofr.de>
Date: Thu, 3 Oct 2024 10:49:24 +0200
Subject: [PATCH] add replicaton module to reference documentation

---
 docs/reference/Replication.md      | 13 +++++++++++++
 mkdocs.yaml                        |  1 +
 src/osmium/replication/__init__.py |  6 ++++++
 src/osmium/replication/server.py   | 22 +++++++++++++++++-----
 src/osmium/replication/utils.py    |  5 +++++
 5 files changed, 42 insertions(+), 5 deletions(-)
 create mode 100644 docs/reference/Replication.md

diff --git a/docs/reference/Replication.md b/docs/reference/Replication.md
new file mode 100644
index 00000000..efb64bc9
--- /dev/null
+++ b/docs/reference/Replication.md
@@ -0,0 +1,13 @@
+# Replication
+
+## Replication server
+
+::: osmium.replication.ReplicationServer
+::: osmium.replication.OsmosisState
+::: osmium.replication.DownloadResult
+
+
+## Repliction utils
+
+::: osmium.replication.get_replication_header
+::: osmium.replication.ReplicationHeader
diff --git a/mkdocs.yaml b/mkdocs.yaml
index faca0082..3c9d3f12 100644
--- a/mkdocs.yaml
+++ b/mkdocs.yaml
@@ -45,6 +45,7 @@ nav:
       - Geometry Processing: 'reference/Geometry-Functions.md'
       - Area Building: 'reference/Area.md'
       - Indexes: 'reference/Indexes.md'
+      - Replication: 'reference/Replication.md'
       - Exceptions: 'reference/Exceptions.md'
 
 exclude_docs: |
diff --git a/src/osmium/replication/__init__.py b/src/osmium/replication/__init__.py
index 989b4745..5ab7b088 100644
--- a/src/osmium/replication/__init__.py
+++ b/src/osmium/replication/__init__.py
@@ -5,3 +5,9 @@
 # Copyright (C) 2023 Sarah Hoffmann <lonvia@denofr.de> and others.
 # For a full list of authors see the git log.
 from ._replication import *
+
+from .server import (ReplicationServer as ReplicationServer,
+                     OsmosisState as OsmosisState,
+                     DownloadResult as DownloadResult)
+from .utils import (ReplicationHeader as ReplicationHeader,
+                    get_replication_header as get_replication_header)
diff --git a/src/osmium/replication/server.py b/src/osmium/replication/server.py
index dfa262ab..787fecf1 100644
--- a/src/osmium/replication/server.py
+++ b/src/osmium/replication/server.py
@@ -28,29 +28,41 @@
 LOG.addHandler(logging.NullHandler())
 
 class OsmosisState(NamedTuple):
+    """ Represents a state file of a replication server.
+    """
     sequence: int
+    "The ID of the replication change on the server."
     timestamp: dt.datetime
+    "Date until when changes are contained in the change file."
 
 class DownloadResult(NamedTuple):
+    """ Downloaded change.
+    """
     id: int
+    "The ID of the latest downloaded replication change on the server."
     reader: MergeInputReader
+    "[osmium.MergeInputReader][] with all downloaded changes."
     newest: int
+    "ID of the newest change available on the server."
 
 class ReplicationServer:
     """ Represents a connection to a  server that publishes replication data.
         Replication change files allow to keep local OSM data up-to-date without
         downloading the full dataset again.
 
-        `url` contains the base URL of the replication service. This is the
-        directory that contains the state file with the current state. If the
-        replication service serves something other than osc.gz files, set
-        the `diff_type` to the given file suffix.
-
         ReplicationServer may be used as a context manager. In this case, it
         internally keeps a connection to the server making downloads faster.
     """
 
     def __init__(self, url: str, diff_type: str = 'osc.gz') -> None:
+        """ Set up the connection to a replication server.
+
+            `url` contains the base URL of the replication service. This is
+            the directory that contains the state file with the current
+            state. If the replication service serves something other
+            than osc.gz files, set the `diff_type` to the given file suffix.
+        """
+
         self.baseurl = url
         self.diff_type = diff_type
         self.extra_request_params: dict[str, Any] = dict(timeout=60, stream=True)
diff --git a/src/osmium/replication/utils.py b/src/osmium/replication/utils.py
index ab020f92..5518532e 100644
--- a/src/osmium/replication/utils.py
+++ b/src/osmium/replication/utils.py
@@ -15,9 +15,14 @@
 LOG = logging.getLogger('pyosmium')
 
 class ReplicationHeader(NamedTuple):
+    """ Description of a replication state.
+    """
     url: Optional[str]
+    "Base URL of the replication service."
     sequence: Optional[int]
+    "ID of the change file on the server."
     timestamp: Optional[dt.datetime]
+    "Date of latest changes contained in the diff file."
 
 
 def get_replication_header(fname: str) -> ReplicationHeader: