Merge pull request #215 from josephlewis42/jl/feat/mkdocs

Added mkdocs

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add `filesystem.validate_folder_writable` to check if a folder can be written to #200
 - Expose `constants.VERSION` to have access to zimscraperlib version from scrapers #224
+- Added mkdocs based documentation site. #92
 
 ### Fixed
 

docs/index.md

@@ -0,0 +1,7 @@
+---
+title: zimscraperlib 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,43 @@
+"""
+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 / "src"
+api_reference = Path("api_reference")
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+
+    # Package docs get the parent module name.
+    if module_path.name == "__init__":
+        module_path = module_path.parent
+    elif 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"---\ntitle: {identifier}\n---\n\n::: {identifier}")
+
+    # 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())

mkdocs.yml

@@ -0,0 +1,92 @@
+site_name: Python Scraperlib
+site_description: 'Collection of Python code to re-use across Python-based OpenZIM scrapers.'
+repo_url: https://github.com/openzim/python-scraperlib
+repo_name: GitHub
+edit_uri: edit/main/docs/
+
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+
+nav:
+  - Home: index.md
+  - Design:
+      - Functional Architecture: functional_architecture.md
+      - Software Architecture: software_architecture.md
+      - Technical Architecture: technical_architecture.md
+  - API Reference: api_reference/
+  - License: license.md
+
+theme:
+  name: material
+  logo: assets/openzim.png
+  palette:
+    # Light mode
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    # Use XHR for page changes to avoid page flash during navigation.
+    - navigation.instant
+    - navigation.instant.progress
+    # Use tabs and section headers rather than a single side navbar.
+    - navigation.tabs
+    - navigation.sections
+    # Add buttons to edit content
+    - content.action.edit
+
+markdown_extensions:
+  - pymdownx.snippets:
+      base_path: .
+      check_paths: true
+
+plugins:
+  - search
+
+  # Replace externally hosted assets for compliance with various privacy regulations.
+  - privacy
+
+  # Nicely include markdown, e.g. to rewrite relative links
+  - include-markdown
+
+  # Generate API docs and navigation for them
+  - gen-files:
+      scripts:
+        - docs/scripts/generate_api_nav.py
+
+  # Import additional nav from NAVIGATION.md files, like the one produced
+  # by gen-files.
+  - literate-nav:
+      nav_file: NAVIGATION.md
+
+  # Generate items
+  - mkdocstrings:
+      handlers:
+        python:
+          # Set up cross-references to Python types
+          import:
+            - https://docs.python.org/3/objects.inv
+          paths: [src]
+          options:
+            docstring_section_style: list
+            filters: ['!^_']
+            heading_level: 2
+            inherited_members: true
+            merge_init_into_class: true
+            separate_signature: true
+            show_signature_annotations: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            signature_crossrefs: true
+            summary: true
+            # Typically this should be off, but zimscraperlib has many
+            # items that won't be picked up because they lack docs
+            # or are using single line comments (like constants).
+            show_if_no_docstring: true

pyproject.toml

@@ -131,6 +131,24 @@ features = ["scripts", "check"]
 pyright = "inv check-pyright --args '{args}'"
 all = "inv checkall --args '{args}'"
 
+[tool.hatch.envs.docs]
+template = "docs"
+detached = true
+dependencies = [
+  "mkdocs==1.6.1",
+  "mkdocstrings[python]==0.27.0",
+  "mkdocs-material==9.5.44",
+  "pymdown-extensions==10.12",
+  "mkdocs-gen-files==0.5.0",
+  "mkdocs-literate-nav==0.6.1",
+  "mkdocs-include-markdown-plugin==7.1.2",
+  "black==24.10.0",
+]
+
+[tool.hatch.envs.docs.scripts]
+serve = "mkdocs serve"
+build = "mkdocs build"
+
 [tool.black]
 line-length = 88
 target-version = ['py312']

src/zimscraperlib/image/optimization.py

@@ -68,15 +68,15 @@ def optimize_png(
     Arguments:
         reduce_colors: Whether to reduce colors using adaptive color pallette (boolean)
             values: True | False
-        max_colors: Maximum number of colors
-        if reduce_colors is True (integer between 1 and 256)
+        max_colors: Maximum number of colors if reduce_colors is True (integer between
+            1 and 256)
             values: 35 | 64 | 256 | 128 | XX
         fast_mode: Whether to use faster but weaker compression (boolean)
             values: True | False
         remove_transparency: Whether to remove transparency (boolean)
             values: True | False
-        background_color: Background color
-        if remove_transparency is True (tuple containing RGB values)
+        background_color: Background color if remove_transparency is True (tuple
+            containing RGB values)
             values: (255, 255, 255) | (221, 121, 108) | (XX, YY, ZZ)"""
 
     ensure_matches(src, "PNG")
@@ -110,13 +110,15 @@ def optimize_jpeg(
     **_,
 ) -> pathlib.Path | io.BytesIO:
     """method to optimize JPEG files using a pure python external optimizer
-    quality: JPEG quality (integer between 1 and 100)
-        values: 50 | 55 | 35 | 100 | XX
-    keep_exif: Whether to keep EXIF data in JPEG (boolean)
-        values: True | False
-    fast_mode: Use the supplied quality value. If turned off, optimizer will
-               get dynamic quality value to ensure better compression
-        values: True | False"""
+
+    Arguments:
+        quality: JPEG quality (integer between 1 and 100)
+            values: 50 | 55 | 35 | 100 | XX
+        keep_exif: Whether to keep EXIF data in JPEG (boolean)
+            values: True | False
+        fast_mode: Use the supplied quality value. If turned off, optimizer will
+                get dynamic quality value to ensure better compression
+            values: True | False"""
 
     ensure_matches(src, "JPEG")
 
@@ -179,14 +181,16 @@ def optimize_webp(
     **_,
 ) -> pathlib.Path | io.BytesIO:
     """method to optimize WebP using Pillow options
-    lossless: Whether to use lossless compression (boolean)
-        values: True | False
-    quality: WebP quality for lossy, effort put into compression
-    for lossless (integer between 0 to 100)
-        values: 30 | 45 | 100 | XX
-    method: Quality/speed trade-off;
-    higher values give better compression (integer between 1 and 6)
-        values: 1 | 2 | 3 | 4 | 5 | 6
+
+    Arguments:
+        lossless: Whether to use lossless compression (boolean);
+            values: True | False
+        quality: WebP quality for lossy, effort put into compression for lossless
+            (integer between 0 to 100);
+            values: 30 | 45 | 100 | XX
+        method: Quality/speed trade-off; higher values give better compression (integer
+            between 1 and 6);
+            values: 1 | 2 | 3 | 4 | 5 | 6
 
     refer to the link for more details
     https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#webp"""
@@ -230,18 +234,21 @@ def optimize_gif(
     **_,
 ) -> pathlib.Path:
     """method to optimize GIFs using gifsicle >= 1.92
-    optimize_level: Optimization level;
-    higher values give better compression (integer between 1 and 3)
-        values: 1 | 2 | 3
-    lossiness: Level of lossy optimization to use;
-    higher values give better compression (integer)
-        values: 20 | 45 | 80 | XX
-    interlace: Whether to interlace the frames (boolean)
-        values: True | False
-    no_extensions: Whether to remove all extension options from GIF (boolean)
-        values: True | False
-    max_colors: Maximum number of colors in resultant GIF (integer between 2 and 256)
-        values: 2 | 86 | 128 | 256 | XX
+
+    Arguments:
+        optimize_level: Optimization level; higher values give better compression
+            (integer between 1 and 3);
+            values: 1 | 2 | 3
+        lossiness: Level of lossy optimization to use; higher values give better
+            compression (integer)
+            values: 20 | 45 | 80 | XX
+        interlace: Whether to interlace the frames (boolean)
+            values: True | False
+        no_extensions: Whether to remove all extension options from GIF (boolean)
+            values: True | False
+        max_colors: Maximum number of colors in resultant GIF;
+            (integer between 2 and 256)
+            values: 2 | 86 | 128 | 256 | XX
 
     refer to the link for more details - https://www.lcdf.org/gifsicle/man.html"""
 
@@ -282,12 +289,13 @@ def optimize_image(
 ):
     """Optimize image, automatically selecting correct optimizer
 
-    delete_src: whether to remove src file upon success (boolean)
-        values: True | False
-    convert: whether/how to convert from source before optimizing (str or boolean)
-        values: False: don't convert
-                True: convert to format implied by dst suffix
-                "FMT": convert to format FMT (use Pillow names)"""
+    Arguments:
+        delete_src: whether to remove src file upon success (boolean)
+            values: True | False
+        convert: whether/how to convert from source before optimizing (str or boolean)
+            values: False: don't convert
+                    True: convert to format implied by dst suffix
+                    "FMT": convert to format FMT (use Pillow names)"""
 
     src_format, dst_format = format_for(src, from_suffix=False), format_for(dst)