feat: add docs (#4)

.github/workflows/docs.yaml

@@ -0,0 +1,26 @@
+name: Docs
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  pages: write
+
+jobs:
+  docs:
+    name: Deploy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v3
+      - run: uv sync
+      - run: uv run maturin develop
+      - env:
+          GIT_COMMITTER_NAME: CI
+          GIT_COMMITTER_EMAIL: [email protected]
+        run: uv run mike deploy ${{ github.ref_name}} latest --update-aliases --push

.pre-commit-config.yaml

@@ -4,7 +4,6 @@ repos:
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
-      - id: check-yaml
       - id: check-added-large-files
   - repo: local
     hooks:

README.md

@@ -25,6 +25,12 @@ assert result == {
 python -m pip install hydraters
 ```
 
+Or, if you're using **uv**:
+
+```shell
+uv add hydraters
+```
+
 ## Developing
 
 Get [Rust](https://rustup.rs/) and [uv](https://docs.astral.sh/uv/getting-started/installation/).

docs/api.md

@@ -0,0 +1,9 @@
+# API
+
+The **hydraters** API.
+
+::: hydraters.dehydrate
+
+::: hydraters.hydrate
+
+::: hydraters.DO_NOT_MERGE_MARKER

docs/index.md

@@ -0,0 +1 @@
+../README.md

docs/overrides/stylesheets/extra.css

@@ -0,0 +1,40 @@
+:root,
+[data-md-color-scheme="default"] {
+  /* --md-heading-font: "Oswald"; */
+  --md-primary-fg-color: #cf3f02;
+  --md-default-fg-color: #443f3f;
+  --boxShadowD: 0px 12px 24px 0px rgba(68, 63, 63, 0.08),
+    0px 0px 4px 0px rgba(68, 63, 63, 0.08);
+}
+body {
+  margin: 0;
+  padding: 0;
+  /* font-size: 16px; */
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: var(--md-heading-font);
+  font-weight: bold;
+}
+.md-typeset h1,
+.md-typeset h2,
+.md-typeset h3,
+.md-typeset h4 {
+  font-weight: normal;
+  color: var(--md-default-fg-color);
+}
+.md-button,
+.md-typeset .md-button {
+  font-family: var(--md-heading-font);
+}
+.md-content .supheading {
+  font-family: var(--md-heading-font);
+  text-transform: uppercase;
+  color: var(--md-primary-fg-color);
+  font-size: 0.75rem;
+  font-weight: bold;
+}

hydraters.pyi

@@ -4,7 +4,30 @@ DO_NOT_MERGE_MARKER: str
 """The magic marker that is used to indicate that a field should not be merged."""
 
 def hydrate(base: dict[str, Any], item: dict[str, Any]) -> dict[str, Any]:
-    """Hydrates an item using a base."""
+    """Hydrates an item using a base.
+
+    Args:
+        base:
+            The base item to use for hydration. Any values on the base that are
+            not on the item will be added back to the item.
+        item:
+            The item to hydrate. The item is mutated in-place and also returned.
+
+    Returns:
+        The hydrated item.
+    """
 
 def dehydrate(base: dict[str, Any], item: dict[str, Any]) -> dict[str, Any]:
-    """Dehydrates an item using a base."""
+    """Dehydrates an item using a base.
+
+    Args:
+        base:
+            The base item to use for dehydration. Any values that are equal on
+            the base and the itm will be removed from the item.
+        item:
+            The item to be dehydrated. The item is mutated in-place, and also
+            returned.
+
+    Returns:
+        The dehydrated item.
+    """

mkdocs.yml

@@ -0,0 +1,112 @@
+site_name: hydraters
+site_url: https://developmentseed.org/hydraters/
+repo_name: developmentseed/hydraters
+repo_url: https://github.com/developmentseed/hydraters
+site_author: Development Seed
+docs_dir: docs
+
+extra:
+  social:
+    - icon: "fontawesome/brands/github"
+      link: "https://github.com/developmentseed"
+    - icon: "fontawesome/brands/twitter"
+      link: "https://twitter.com/developmentseed"
+    - icon: "fontawesome/brands/linkedin"
+      link: "https://www.linkedin.com/company/development-seed"
+  version:
+    provider: mike
+
+nav:
+  - README: index.md
+  - api.md
+
+theme:
+  name: material
+  logo: img/logo_no_text.png
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      primary: default
+      accent: deep orange
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: default
+      accent: deep orange
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+  font:
+    text: Roboto
+    code: Roboto Mono
+  features:
+    - content.code.annotate
+    - content.code.copy
+    - navigation.indexes
+    - navigation.instant
+    - navigation.tracking
+    - search.suggest
+    - search.share
+
+extra_css:
+  - overrides/stylesheets/extra.css
+
+plugins:
+  - search
+  - social
+  - mike:
+      alias_type: "copy"
+      canonical_version: "latest"
+  - mkdocstrings:
+      enable_inventory: true
+      handlers:
+        python:
+          paths: [obstore/python]
+          options:
+            # We set allow_inspection: false to ensure that all docstrings come
+            # from the pyi files, not the Rust-facing doc comments.
+            allow_inspection: false
+            docstring_section_style: list
+            docstring_style: google
+            line_length: 80
+            separate_signature: true
+            show_root_heading: true
+            show_signature_annotations: true
+            show_source: false
+            show_symbol_type_toc: true
+            signature_crossrefs: true
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - codehilite:
+      guess_lang: false
+  - def_list
+  - footnotes
+  - md_in_html
+  - pymdownx.arithmatex
+  - pymdownx.betterem
+  - pymdownx.caret:
+      insert: false
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.escapeall:
+      hardbreak: true
+      nbsp: true
+  - pymdownx.magiclink:
+      hide_protocol: true
+      repo_url_shortener: true
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+  - toc:
+      permalink: true

pyproject.toml

@@ -31,4 +31,13 @@ requires = ["maturin>=1.7,<2.0"]
 build-backend = "maturin"
 
 [dependency-groups]
-dev = ["mypy>=1.13.0", "pre-commit>=3.5.0", "pytest>=8.3.3", "ruff>=0.7.3"]
+dev = [
+    "mike>=2.1.3",
+    "mkdocs-material[imaging]>=9.5.44",
+    "mkdocstrings-python>=1.12.2",
+    "mkdocstrings>=0.27.0",
+    "mypy>=1.13.0",
+    "pre-commit>=3.5.0",
+    "pytest>=8.3.3",
+    "ruff>=0.7.3",
+]