Add docs with mkdocs

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    name: GitHub Pages
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout the Repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Setup Python
+        run: uv python install
+
+      - name: Install mkdocs dependencies
+        run: uv venv && uv pip install -r docs/requirements.txt
+
+      - name: Install numcodecs-safeguards
+        run: uv pip install .
+
+      - name: Build the documentation
+        run: uv run mkdocs build
+
+      - name: Deploy the Documentation
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./site
+          keep_files: false

docs/index.md

@@ -0,0 +1 @@
+# data-loader

docs/js/katex.js

@@ -0,0 +1,8 @@
+document.addEventListener("DOMContentLoaded", () => {
+    renderMathInElement(document.body, {
+        delimiters: [
+            { left: "\\(", right: "\\)", display: false },
+            { left: "\\[", right: "\\]", display: true }
+        ],
+    })
+});

docs/requirements.txt

@@ -0,0 +1,8 @@
+mkdocs
+mkdocstrings[python]
+mkdocs-exclude
+mkdocstrings-python-generator==1.0.0rc1
+
+Pygments
+
+ruff

mkdocs.yml

@@ -0,0 +1,71 @@
+site_name: climatebenchpress.data-loader
+
+strict: true
+
+markdown_extensions:
+  - footnotes
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      use_pygments: true
+      noclasses: true
+  - pymdownx.arithmatex:
+      generic: true
+
+extra_javascript:
+  - js/katex.js
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js
+
+extra_css:
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css
+
+theme:
+  name: readthedocs
+  highlightjs: false
+  navigation_depth: 99
+
+nav:
+  - Home: index.md
+  - Links:
+      - GitHub: https://github.com/ClimateBenchPress/data-loader/
+      - PyPI: https://pypi.org/project/climatebenchpress-data-loader/
+
+plugins:
+  - exclude:
+      glob:
+        - requirements.txt
+  - search
+  - autorefs
+  - mkdocstrings-python-generator:
+      source_dirs:
+        - nav_heading: [Documentation]
+          base: src
+  - mkdocstrings:
+      enable_inventory: true
+      handlers:
+        python:
+          options:
+            docstring_section_style: list
+            docstring_style: numpy
+            show_if_no_docstring: true
+            filters: ["!^_$", "!^_[^_]", "!^__", "__init__"]
+            members_order: source
+            group_by_category: false
+            show_source: false
+            separate_signature: true
+            show_signature_annotations: true
+            signature_crossrefs: true
+            show_root_toc_entry: false
+            merge_init_into_class: true
+            annotations_path: source
+            summary:
+              attributes: false
+              classes: true
+              functions: true
+              modules: true
+          inventories:
+            - https://docs.python.org/3.12/objects.inv
+            - https://docs.xarray.dev/en/v2025.03.0/objects.inv
+
+watch:
+  - src