chore: configure mkdocs and lint some mypy stuff

docs/css/style.css

@@ -0,0 +1,10 @@
+/* set primary color */
+:root {
+  --md-primary-fg-color:        #00C9BF;
+  --md-accent-fg-color:         #00C9BF;
+}
+
+/* make code selectable on main */
+.highlight .o {
+    user-select: none;
+}

docs/gen_ref_pages.py

@@ -0,0 +1,35 @@
+"""Generate the code reference pages and navigation.
+
+From https://mkdocstrings.github.io/recipes/
+"""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+for path in sorted(Path("suisa_sendemeldung").rglob("*.py")):
+    module_path = path.relative_to("suisa_sendemeldung").with_suffix("")
+    doc_path = path.relative_to("suisa_sendemeldung").with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = list(module_path.parts)
+
+    if parts[-1] == "__init__":
+        continue
+    elif parts[-1] == "__main__":
+        continue
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        identifier = ".".join(parts)
+        print("::: " + identifier, file=fd)
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)  #
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())
+
+readme = Path("README.md").open("r")
+with mkdocs_gen_files.open("index.md", "w") as index_file:
+    index_file.writelines(readme.read())

mkdocs.yaml

@@ -0,0 +1,56 @@
+site_name: SUISA Sendemeldung
+repo_url: https://github.com/radiorabe/suisa_sendemeldung
+repo_name: radiorabe/suisa_sendemeldung
+
+theme:
+  name: "material"
+  palette:
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: '#00c9bf'
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+    # Palette toggle for light mode
+    - scheme: default
+      primary: '#00c9bf'
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+  icon:
+    repo: fontawesome/brands/git-alt
+  features:
+    - content.code.copy
+    - toc.integrate
+
+markdown_extensions:
+- pymdownx.highlight:
+    anchor_linenums: true
+- pymdownx.inlinehilite
+- pymdownx.snippets
+- pymdownx.superfences
+
+extra_css:
+- css/style.css
+
+plugins:
+- search
+- autorefs
+- gen-files:
+    scripts:
+    - docs/gen_ref_pages.py
+- literate-nav:
+    nav_file: SUMMARY.md
+- section-index
+- mkdocstrings:
+    handlers:
+      python:
+        paths: [suisa_sendemeldung]
+
+nav:
+  - README: index.md
+  - Python Reference: reference/
+
+watch:
+  - README.md
+  - suisa_sendemeldung/

pyproject.toml

@@ -42,6 +42,13 @@ pytest-pylint = ">=0.19,<0.22"
 requests-mock = "^1.11.0"
 types-requests = "^2.31.0.1"
 wheel = ">=0.40,<0.44"
+mkdocs = "^1.5.3"
+mkdocs-material = "^9.5.14"
+mkdocs-gen-files = "^0.5.0"
+mkdocs-literate-nav = "^0.6.1"
+mkdocs-section-index = "^0.3.8"
+mkdocs-autorefs = "^1.0.1"
+mkdocstrings = {extras = ["python"], version = "^0.24.1"}
 
 [tool.isort]
 profile = "black"
@@ -51,7 +58,6 @@ minversion = "7.4"
 addopts = "--doctest-modules --cov=suisa_sendemeldung --pylint --cov-fail-under=100 --ignore=docs/"
 filterwarnings = [
     "ignore::DeprecationWarning:pylint",
-    "ignore::pytest.PytestRemovedIn8Warning:pytest_pylint",
 ]
 
 [build-system]

suisa_sendemeldung/acrclient.py

@@ -8,10 +8,12 @@
 
 
 class ACRClient(Client):
-    """ACRCloud client to fetch metadata.
+    """ACRCloud client wrapper to fetch metadata.
 
-    Args:
+    Arguments:
+    ---------
         bearer_token: The bearer token for ACRCloud.
+
     """
 
     # format of timestamp in api answer
@@ -24,18 +26,25 @@ def __init__(self, bearer_token, base_url="https://eu-api-v2.acrcloud.com"):
         self.default_date = date.today() - timedelta(days=1)
 
     def get_data(
-        self, project_id, stream_id, requested_date=None, timezone=ACR_TIMEZONE
+        self,
+        project_id,
+        stream_id,
+        requested_date=None,
+        timezone=ACR_TIMEZONE,
     ):
         """Fetch metadata from ACRCloud for `stream_id`.
 
-        Args:
+        Arguments:
+        ---------
             project_id: The Project ID of the stream.
             stream_id: The ID of the stream.
             requested_date (optional): The date of the entries you want (default: yesterday).
             timezone (optional): The timezone to use for localization.
 
         Returns:
+        -------
             json: The ACR data from date
+
         """
         if requested_date is None:
             requested_date = self.default_date
@@ -49,27 +58,35 @@ def get_data(
         for entry in data:
             metadata = entry.get("metadata")
             ts_utc = pytz.utc.localize(
-                datetime.strptime(metadata.get("timestamp_utc"), ACRClient.TS_FMT)
+                datetime.strptime(metadata.get("timestamp_utc"), ACRClient.TS_FMT),
             )
             ts_local = ts_utc.astimezone(pytz.timezone(timezone))
             metadata.update({"timestamp_local": ts_local.strftime(ACRClient.TS_FMT)})
 
         return data
 
     def get_interval_data(
-        self, project_id, stream_id, start, end, timezone=ACR_TIMEZONE
+        self,
+        project_id,
+        stream_id,
+        start,
+        end,
+        timezone=ACR_TIMEZONE,
     ):  # pylint: disable-msg=too-many-locals,too-many-arguments
         """Get data specified by interval from start to end.
 
-        Args:
+        Arguments:
+        ---------
             project_id: The ID of the project.
             stream_id: The ID of the stream.
             start: The start date of the interval.
             end: The end date of the interval.
             timezone (optional): will be passed to `get_data()`.
 
         Returns:
+        -------
             json: The ACR data from start to end.
+
         """
         trim = False
         # if we have to localize the timestamps we may need more data
@@ -100,7 +117,10 @@ def get_interval_data(
         ljust_amount: int = 27
         for ptr in tqdm(dates, desc="load ACRCloud data".ljust(ljust_amount)):
             data += self.get_data(
-                project_id, stream_id, requested_date=ptr, timezone=timezone
+                project_id,
+                stream_id,
+                requested_date=ptr,
+                timezone=timezone,
             )
 
         # if timestamps are localized we will have to removed the unneeded entries.