Migrate docs to zensical (#789)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: tobiasraabe

.pre-commit-config.yaml

@@ -48,11 +48,12 @@ repos:
     hooks:
     -   id: mdformat
         additional_dependencies: [
-            mdformat-myst,
+            mdformat-mkdocs,
             mdformat-ruff,
             mdformat-pyproject>=0.0.2,
         ]
         files: (docs/.)
+        exclude: (docs/source/reference_guides/hookspecs\.md|docs/source/api/.*\.md|docs/source/how_to_guides/capture_warnings\.md|docs/source/how_to_guides/hashing_inputs_of_tasks\.md|docs/source/how_to_guides/provisional_nodes_and_task_generators\.md|docs/source/how_to_guides/remote_files\.md|docs/source/how_to_guides/writing_custom_nodes\.md|docs/source/tutorials/defining_dependencies_products\.md|docs/source/tutorials/using_a_data_catalog\.md)
 -   repo: https://github.com/kynan/nbstripout
     rev: 0.9.1
     hooks:

.readthedocs.yaml

@@ -1,19 +1,25 @@
 version: 2
 
-sphinx:
-  configuration: docs/source/conf.py
+mkdocs:
+  configuration: mkdocs.yml
   fail_on_warning: true
 
 build:
   os: ubuntu-24.04
   tools:
     python: "3.13"
   jobs:
-      pre_create_environment:
-         - asdf plugin add uv
-         - asdf install uv latest
-         - asdf global uv latest
-      create_environment:
-         - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
-      install:
-         - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group docs
+    pre_create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    create_environment:
+      - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group docs
+    build:
+      html:
+        - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv run --group docs zensical build
+    post_build:
+      - mkdir -p "${READTHEDOCS_OUTPUT}/html"
+      - cp -a docs/build/. "${READTHEDOCS_OUTPUT}/html/"

AGENTS.md

@@ -0,0 +1,32 @@
+# AGENTS
+
+Guidance for coding agents working in this repository.
+
+## Tooling
+
+- Use `uv` for Python environments, dependencies, and running commands.
+- Use `just` as the primary task runner.
+- Use `rg` for fast code search.
+- `ast-grep` and `fastmod` are available for structural refactors.
+- `pixi` is available when needed.
+
+## Setup
+
+- Install dependencies:
+  - `just install`
+  - or `uv sync --all-groups`
+
+## Validation Commands
+
+- Lint:
+  - `just lint`
+- Type checking:
+  - `just typing`
+- Tests:
+  - `just test`
+- Full verification:
+  - `just check`
+
+For targeted tests, prefer:
+
+- `uv run --group test pytest tests/path/to/test_file.py -k "pattern"`

CHANGELOG.md

@@ -0,0 +1,33 @@
+# Documentation
+
+- Link to existing docs/API refs instead of re-explaining concepts - reduces duplication
+    and keeps info in sync - Prevents documentation drift and outdated explanations by
+    maintaining a single source of truth for each concept
+- Link to canonical docs rather than duplicating content - prevents drift and
+    maintenance burden - Consolidating documentation into existing files with
+    cross-references keeps information consistent and reduces the effort needed to
+    update multiple locations when changes occur.
+- Document only public APIs and user-facing behavior - exclude internals, framework
+    abstractions, and implementation plumbing - Users need actionable documentation on
+    what they can use, not confusing details about internal mechanics they can't control
+- Explain before showing - place explanatory text before code examples, not after -
+    Users need context to understand code examples; "explain then show" improves
+    comprehension and reduces confusion
+- Create dedicated pages for substantial features - ensures discoverability and
+    comprehensive coverage vs. fragmented mentions - Prevents users from missing
+    features when they approach from different contexts (CLI vs. API) and allows
+    features to be documented holistically rather than buried in subsections.
+- Avoid `# ruff: noqa` or `# type: ignore` in doc examples - ensures examples stay
+    correct and runnable - Skip directives hide bugs and type errors in documentation
+    code that users will copy, leading to broken examples in the wild
+- Explicitly mark parameters/features as 'optional' in docs, even when types show it -
+    reduces cognitive load for readers - Users shouldn't need to parse type signatures
+    to understand optionality; explicit labels make documentation scannable and
+    accessible to all skill levels
+- Remove documentation sections explaining standard behavior that "just works" - keeps
+    docs focused on actionable, non-obvious information - Users don't need explanations
+    of things that work automatically; documentation should focus on configuration
+    requirements, edge cases, and non-obvious behaviors that affect usage decisions
+- Strip boilerplate from docs examples - show only the feature being demonstrated -
+    Reduces cognitive load and helps readers focus on the specific API or pattern being
+    taught without distraction from scaffolding code.

docs/AGENTS.md

@@ -0,0 +1 @@
+AGENTS.md

docs/CLAUDE.md

@@ -1,31 +1,129 @@
 /* Classes for the index page. */
-.index-card-image {
-    padding-top: 1rem;
-    height: 68px;
+.home-tiles {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 1rem;
+    margin: 1.25rem 0 1rem;
+}
+
+.home-tile {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 0.55rem;
+    padding: 1rem 1.1rem;
+    border: 1px solid rgba(15, 23, 42, 0.14);
+    border-radius: 14px;
+    background: #ffffff;
+    color: inherit;
+    text-decoration: none;
     text-align: center;
+    box-shadow: 0 3px 10px rgba(15, 23, 42, 0.11);
+    transition:
+        transform 120ms ease-in-out,
+        box-shadow 120ms ease-in-out,
+        border-color 120ms ease-in-out;
+}
+
+.home-tile,
+.home-tile:hover,
+.home-tile:focus,
+.home-tile:focus-visible,
+.home-tile * {
+    text-decoration: none;
+}
+
+.home-tile:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 10px 22px rgba(15, 23, 42, 0.16);
+    border-color: #91a9ca;
+}
+
+.md-typeset a.home-tile,
+.md-typeset a.home-tile:hover,
+.md-typeset a.home-tile:focus,
+.md-typeset a.home-tile:focus-visible,
+.md-typeset a.home-tile:active,
+.md-typeset a.home-tile:visited {
+    text-decoration: none !important;
+    border-bottom: 0 !important;
+    background-image: none !important;
+    color: inherit !important;
+}
+
+body[data-md-color-scheme="default"] .md-typeset a.home-tile,
+body[data-md-color-scheme="default"] .md-typeset a.home-tile:hover,
+body[data-md-color-scheme="default"] .md-typeset a.home-tile:focus,
+body[data-md-color-scheme="default"] .md-typeset a.home-tile:focus-visible,
+body[data-md-color-scheme="default"] .md-typeset a.home-tile:active,
+body[data-md-color-scheme="default"] .md-typeset a.home-tile:visited {
+    background: #ffffff !important;
+    background-color: #ffffff !important;
 }
 
-.index-card-link {
-    color: var(--sd-color-card-text);
-    font-weight: bold;
+.md-typeset a.home-tile *,
+.md-typeset a.home-tile:hover *,
+.md-typeset a.home-tile:focus *,
+.md-typeset a.home-tile:focus-visible *,
+.md-typeset a.home-tile:active *,
+.md-typeset a.home-tile:visited * {
+    text-decoration: none !important;
+    border-bottom: 0 !important;
+    background-image: none !important;
 }
 
-pre {
-  padding-left: 20px
+.home-tile h3 {
+    margin: 0;
+    font-size: 1.05rem;
 }
 
+.home-tile p {
+    margin: 0;
+    color: inherit;
+    line-height: 1.45;
+}
+
+.home-tile img {
+    width: 44px;
+    height: 44px;
+    object-fit: contain;
+}
+
+@media (max-width: 760px) {
+    .home-tiles {
+        grid-template-columns: 1fr;
+    }
+}
+
+pre,
 li pre {
-  padding-left: 20px
+    padding-left: 0;
+}
+
+body[data-md-color-scheme="slate"] .home-tile {
+    border-color: rgba(203, 213, 225, 0.24);
+    background: rgba(15, 23, 42, 0.38);
+    box-shadow: 0 4px 12px rgba(2, 6, 23, 0.38);
 }
 
-.highlight {
-    background: #f5f5f5
+body[data-md-color-scheme="slate"] .home-tile:hover {
+    border-color: rgba(147, 197, 253, 0.55);
+    box-shadow: 0 12px 26px rgba(2, 6, 23, 0.46);
 }
 
-.highlight button.copybtn{
-    background-color: #f5f5f5;
+body[data-md-color-scheme="slate"] .home-tile p {
+    color: inherit;
 }
 
-.highlight button.copybtn:hover {
-    background-color: #f5f5f5;
+@media (prefers-color-scheme: dark) {
+    .home-tile {
+        border-color: rgba(203, 213, 225, 0.24);
+        background: rgba(15, 23, 42, 0.38);
+        box-shadow: 0 4px 12px rgba(2, 6, 23, 0.38);
+    }
+
+    .home-tile:hover {
+        border-color: rgba(147, 197, 253, 0.55);
+        box-shadow: 0 12px 26px rgba(2, 6, 23, 0.46);
+    }
 }