set up documentation using mkdocs

.readthedocs.yaml

@@ -0,0 +1,18 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: '3.12'
+
+  # custom commands to run mkdocs build within hatch, as suggested by maintainer in
+  # https://github.com/readthedocs/readthedocs.org/issues/10706
+  commands:
+    - pip install hatch
+    - hatch run build-ext
+    - mkdocs build
+    - mkdir --parents $READTHEDOCS_OUTPUT
+    - mv site $READTHEDOCS_OUTPUT/html

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+- Set up documentation using `mkdocs`, published on readthedocs.com (#186)
+
 ## [3.6.0] - 2024-10-15
 
 ### Added

docs/index.md

@@ -0,0 +1,7 @@
+---
+title: libzim Documentation
+---
+
+{%
+    include-markdown "../README.md"
+%}

docs/license.md

@@ -0,0 +1,7 @@
+---
+title: License
+---
+
+```
+--8<-- "LICENSE"
+```

docs/scripts/generate_api_nav.py

@@ -0,0 +1,66 @@
+"""
+Script called by mkdocs-gen-files that generates markdown documents
+with API reference placeholders.
+
+https://oprypin.github.io/mkdocs-gen-files/api.html
+"""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent.parent
+src = root / "libzim"
+api_reference = Path("api_reference")
+
+# Because we are inspecting a compiled module and all the classes can be seen
+# from the `libzim` namespace, their documentation is shown in the home page.
+# We hide them from the home page as their documentation is also shown in the
+# respective modules where they are defined.
+LIBZIM_ROOT_OPTIONS = """
+    options:
+        members: false
+"""
+
+
+for path in sorted(src.rglob("*.pyi")):
+    module_path = path.relative_to(root).with_suffix("")
+
+    # Package docs get the parent module name.
+    if module_path.name == "__init__":
+        module_path = module_path.parent
+        module_options = LIBZIM_ROOT_OPTIONS
+    else:
+        module_options = ""
+
+    if module_path.name.startswith("_"):
+        # Skip other hidden items
+        continue
+    identifier = ".".join(module_path.parts)
+
+    doc_path = identifier + ".md"
+    full_doc_path = api_reference / doc_path
+
+    nav[identifier] = doc_path
+
+    # Create a document with mkdocstrings placeholders.
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        fd.write(
+            f"""---
+title: {identifier}
+---
+
+
+::: {identifier}
+{module_options}
+"""
+        )
+
+    # Make the edit button on the page link to the source file.
+    mkdocs_gen_files.set_edit_path(full_doc_path, Path("..") / path.relative_to(root))
+
+# Write a navigation file that will be interpreted by literate-nav.
+with mkdocs_gen_files.open(api_reference / "NAVIGATION.md", "w") as fd:
+    fd.writelines(nav.build_literate_nav())