Migrate docs to zensical

.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"`

docs/AGENTS.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/CLAUDE.md

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