relcon-docs 0.1.0__py3-none-any.whl

relcon_docs/__init__.py

@@ -0,0 +1 @@
+"""Shared documentation configuration for Relaxed Constraints projects."""

relcon_docs/assets/base.yml

@@ -0,0 +1,63 @@
+# Managed by relcon-docs configure. Do not edit this file.
+# Put project overrides in mkdocs.yml. Paths are relative to that file.
+extra_css:
+- stylesheets/relcon-docs.css
+extra_javascript:
+- javascripts/relcon-docs-math.js
+theme:
+  variant: modern
+  font: false
+  features:
+  - content.action.copy
+  - content.tabs.link
+  - content.code.copy
+  - navigation.tabs
+  - navigation.top
+  - search.highlight
+  palette:
+  - media: (prefers-color-scheme)
+    toggle:
+      icon: lucide/sun-moon
+      name: Switch to light mode
+  - media: '(prefers-color-scheme: light)'
+    scheme: default
+    toggle:
+      icon: lucide/sun
+      name: Switch to dark mode
+  - media: '(prefers-color-scheme: dark)'
+    scheme: slate
+    toggle:
+      icon: lucide/moon
+      name: Switch to system preference
+markdown_extensions:
+  toc:
+    permalink: true
+    permalink_title: Link to this section
+  pymdownx.arithmatex:
+    generic: true
+  admonition: {}
+  pymdownx.details: {}
+  pymdownx.highlight: {}
+  pymdownx.superfences:
+    custom_fences:
+    - name: mermaid
+      class: mermaid
+      format: pymdownx.superfences.fence_code_format
+  pymdownx.tabbed:
+    alternate_style: true
+plugins:
+  llmstxt:
+    sections:
+      Documentation: ["*.md"]
+  search: {}
+  mkdocstrings:
+    handlers:
+      python:
+        options:
+          docstring_style: google
+          members_order: alphabetical
+          filters: ["!^_"]
+          show_signature_annotations: true
+          separate_signature: true
+          signature_crossrefs: true
+          line_length: 76

relcon_docs/assets/docs.yml

@@ -0,0 +1,23 @@
+# Project-owned workflow: configure creates this once and never overwrites it.
+name: Deploy documentation
+
+on:
+  workflow_dispatch: # Allow manual deployment.
+
+  # Uncomment to deploy on pushes to main (for example, consumer projects):
+  # push:
+  #   branches: [main]
+
+  # Or uncomment to deploy on published releases (for example, BONDI):
+  # release:
+  #   types: [published]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  docs:
+    # Replace @main with a reviewed commit SHA to pin the deployment implementation.
+    uses: relaxed-constraints/relcon-docs/.github/workflows/deploy-docs.yml@main

relcon_docs/assets/relcon-docs-math.js

@@ -0,0 +1,34 @@
+/* Load the pinned renderer only when a page contains mathematical notation. */
+(() => {
+  let engine;
+  function renderMath() {
+    if (!document.querySelector('.arithmatex')) return;
+    if (!engine) {
+      engine = new Promise((resolve, reject) => {
+        window.MathJax = {
+          tex: {
+            inlineMath: [['\\(', '\\)']],
+            displayMath: [['\\[', '\\]']],
+            processEscapes: true,
+            processEnvironments: true,
+          },
+          options: { ignoreHtmlClass: '.*|', processHtmlClass: 'arithmatex' },
+          startup: { typeset: false },
+        };
+        const script = document.createElement('script');
+        script.src = 'https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/tex-mml-chtml.js';
+        script.onload = () => resolve(window.MathJax.startup.promise);
+        script.onerror = () => reject(new Error('Could not load the MathJax renderer.'));
+        document.head.appendChild(script);
+      });
+    }
+    engine = engine.then(() => window.MathJax.typesetPromise()).catch(console.error);
+  }
+  if (typeof document$ !== 'undefined') {
+    document$.subscribe(renderMath);
+  } else if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', renderMath);
+  } else {
+    renderMath();
+  }
+})();

relcon_docs/assets/relcon-docs.css

@@ -0,0 +1,111 @@
+/* Button colours are paired for readable labels and visible focus in each theme. */
+:root,
+[data-md-color-scheme="default"] {
+  --relcon-copy-bg: #ffffff;
+  --relcon-copy-hover: #edf1f5;
+  --relcon-copy-border: #7a8796;
+  --relcon-copy-text: #263445;
+}
+
+[data-md-color-scheme="slate"] {
+  --relcon-copy-bg: #222b38;
+  --relcon-copy-hover: #303e50;
+  --relcon-copy-border: #8193aa;
+  --relcon-copy-text: #edf2f8;
+}
+
+.md-typeset button[data-md-copy-url] {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4em;
+  padding: 0.35em 0.65em;
+  background-color: var(--relcon-copy-bg);
+  border: 1px solid var(--relcon-copy-border);
+  color: var(--relcon-copy-text);
+  border-radius: 0.25rem;
+  font-size: 0.65rem;
+  line-height: 1.3;
+}
+
+.md-typeset button[data-md-copy-url]::after {
+  content: attr(aria-label);
+  font-weight: 400;
+}
+
+.md-typeset button[data-md-copy-url]:focus-visible {
+  outline: 2px solid currentColor;
+  outline-offset: 2px;
+}
+
+/* Diagram roles inherit into Zensical's Mermaid shadow roots. */
+:root,
+[data-md-color-scheme="default"] {
+  --relcon-diagram-frame-bg: #f5f7fa;
+  --relcon-diagram-frame-border: #758399;
+  --relcon-diagram-node-bg: #e8eff7;
+  --relcon-diagram-node-border: #59718f;
+  --relcon-diagram-text: #223248;
+  --relcon-diagram-edge: #526780;
+  --relcon-diagram-accent-bg: #fff0cc;
+  --relcon-diagram-accent-border: #a56a12;
+  --relcon-diagram-accent-text: #623a00;
+}
+
+[data-md-color-scheme="slate"] {
+  --relcon-diagram-frame-bg: #202a38;
+  --relcon-diagram-frame-border: #778ba4;
+  --relcon-diagram-node-bg: #293c53;
+  --relcon-diagram-node-border: #8eaacb;
+  --relcon-diagram-text: #eef3f9;
+  --relcon-diagram-edge: #94a9c2;
+  --relcon-diagram-accent-bg: #513b18;
+  --relcon-diagram-accent-border: #e6b65c;
+  --relcon-diagram-accent-text: #fff0cd;
+}
+
+:root,
+[data-md-color-scheme] {
+  /* Native flowcharts need no per-diagram style declarations. */
+  --md-mermaid-node-bg-color: var(--relcon-diagram-node-bg);
+  --md-mermaid-node-fg-color: var(--relcon-diagram-node-border);
+  --md-mermaid-label-fg-color: var(--relcon-diagram-text);
+  --md-mermaid-label-bg-color: var(--md-default-bg-color);
+  --md-mermaid-edge-color: var(--relcon-diagram-edge);
+  --md-mermaid-sequence-actor-bg-color: var(--relcon-diagram-node-bg);
+  --md-mermaid-sequence-actor-border-color: var(--relcon-diagram-node-border);
+  --md-mermaid-sequence-actor-fg-color: var(--relcon-diagram-text);
+  --md-mermaid-sequence-actor-line-color: var(--relcon-diagram-edge);
+  --md-mermaid-sequence-message-fg-color: var(--relcon-diagram-text);
+  --md-mermaid-sequence-message-line-color: var(--relcon-diagram-edge);
+  --md-mermaid-sequence-note-bg-color: var(--relcon-diagram-frame-bg);
+  --md-mermaid-sequence-note-border-color: var(--relcon-diagram-frame-border);
+  --md-mermaid-sequence-note-fg-color: var(--relcon-diagram-text);
+
+  /* Compatibility with diagrams authored before relcon-docs. */
+  --jb-frame-bg: var(--relcon-diagram-frame-bg);
+  --jb-frame-border: var(--relcon-diagram-frame-border);
+  --jb-node-bg: var(--relcon-diagram-node-bg);
+  --jb-node-border: var(--relcon-diagram-node-border);
+  --jb-diagram-text: var(--relcon-diagram-text);
+}
+
+.md-typeset button[data-md-copy-url]:hover {
+  background-color: var(--relcon-copy-hover);
+}
+
+.md-typeset figure {
+  margin: 1.5em 0;
+}
+
+.md-typeset figure img {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  margin-inline: auto;
+}
+
+.md-typeset figcaption {
+  margin-top: 0.75em;
+  color: var(--md-default-fg-color--light);
+  text-align: center;
+}

relcon_docs/cli.py

@@ -0,0 +1,243 @@
+"""Apply packaged defaults without rewriting project-owned configuration."""
+
+import argparse
+import difflib
+import hashlib
+import json
+import os
+import sys
+import tempfile
+from importlib.metadata import version
+from importlib.resources import files
+from pathlib import Path
+
+import yaml
+
+BASE = ".relcon-docs/base.yml"
+STATE = ".relcon-docs/state.json"
+CSS = "docs/stylesheets/relcon-docs.css"
+WORKFLOW = ".github/workflows/docs.yml"
+MATH = "docs/javascripts/relcon-docs-math.js"
+
+
+class ConfigurationError(Exception):
+    """A configuration cannot safely be applied."""
+
+
+def digest(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+
+def managed_assets() -> dict[str, bytes]:
+    assets = files("relcon_docs").joinpath("assets")
+    return {
+        BASE: assets.joinpath("base.yml").read_bytes(),
+        CSS: assets.joinpath("relcon-docs.css").read_bytes(),
+        MATH: assets.joinpath("relcon-docs-math.js").read_bytes(),
+    }
+
+
+def safe_path(root: Path, relative: str) -> Path:
+    """Reject symlinks and non-directory parents before reading or writing."""
+    path = root
+    for part in Path(relative).parts:
+        path = path / part
+        if path.is_symlink():
+            raise ConfigurationError(f"Refusing symlink: {path}")
+        if path != root / relative and path.exists() and not path.is_dir():
+            raise ConfigurationError(f"Expected a directory: {path}")
+    if path.exists() and not path.is_file():
+        raise ConfigurationError(f"Expected a file: {path}")
+    return path
+
+
+def read_state(path: Path, assets: dict[str, bytes]) -> dict[str, str]:
+    if not path.exists():
+        return {}
+    try:
+        state = json.loads(path.read_text())
+        hashes = state["files"]
+        if (
+            state["schema"] != 1
+            or not isinstance(hashes, dict)
+            or set(hashes) not in ({BASE, CSS}, set(assets))
+            or not all(
+                isinstance(value, str)
+                and len(value) == 64
+                and all(char in "0123456789abcdef" for char in value)
+                for value in hashes.values()
+            )
+        ):
+            raise ValueError
+    except (ValueError, KeyError, TypeError) as exc:
+        raise ConfigurationError(
+            f"Invalid state file: {path}. Restore it from Git before configuring."
+        ) from exc
+    return hashes
+
+
+def project_config(root: Path) -> bytes | None:
+    """Validate an existing project or prepare a starter, without editing it."""
+    if (root / "zensical.toml").exists():
+        raise ConfigurationError("Convert zensical.toml to mkdocs.yml first; it takes precedence.")
+    if (root / "mkdocs.yaml").exists():
+        raise ConfigurationError("Rename mkdocs.yaml to mkdocs.yml first.")
+    path = safe_path(root, "mkdocs.yml")
+    if not path.exists():
+        return (
+            "# Project-owned configuration. Override shared defaults here.\n"
+            "# Replace the local site_url with your published URL before deployment.\n"
+            f"INHERIT: {BASE}\n"
+            + yaml.safe_dump(
+                {
+                    "site_name": root.name,
+                    "site_url": "http://127.0.0.1:8000/",
+                },
+                sort_keys=False,
+            )
+        ).encode()
+
+    # Compose rather than construct: existing MkDocs configurations may use
+    # !ENV and Python-name tags, which we must neither execute nor rewrite.
+    try:
+        config = yaml.compose(path.read_text())
+        if not isinstance(config, yaml.MappingNode):
+            raise ValueError
+        settings = {}
+        for key, value in config.value:
+            if not isinstance(key, yaml.ScalarNode) or key.value in settings:
+                raise ValueError
+            settings[key.value] = value
+        inherit = settings.get("INHERIT")
+        if not isinstance(inherit, yaml.ScalarNode) or inherit.value != BASE:
+            raise ConfigurationError(f"Set INHERIT: {BASE} in mkdocs.yml first.")
+        docs_dir = settings.get("docs_dir")
+        if docs_dir is not None and (
+            not isinstance(docs_dir, yaml.ScalarNode) or docs_dir.value not in ("docs", "./docs")
+        ):
+            raise ConfigurationError("This version supports only docs_dir: docs.")
+    except (yaml.YAMLError, ValueError) as exc:
+        raise ConfigurationError("mkdocs.yml must be a YAML mapping with unique keys.") from exc
+    return None
+
+
+def atomic_write(path: Path, content: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = None
+    try:
+        with tempfile.NamedTemporaryFile(dir=path.parent, delete=False) as stream:
+            temporary = Path(stream.name)
+            stream.write(content)
+        os.chmod(temporary, 0o644)
+        os.replace(temporary, path)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+
+
+def configure(root: Path, *, dry_run: bool, check: bool, force: bool) -> int:
+    if not root.is_dir():
+        raise ConfigurationError(f"Project directory does not exist: {root}")
+    assets = managed_assets()
+    paths = {name: safe_path(root, name) for name in [*assets, STATE]}
+    baseline = read_state(paths[STATE], assets)
+    starter = project_config(root)
+    workflow_path = safe_path(root, WORKFLOW)
+    changes = {}
+    conflicts = []
+
+    for name, desired in assets.items():
+        path = paths[name]
+        current = path.read_bytes() if path.exists() else None
+        if current == desired:
+            continue
+        changes[name] = desired
+        if name in baseline:
+            if current is None or digest(current) != baseline[name]:
+                conflicts.append(name)
+        elif current is not None:
+            conflicts.append(name)
+
+    if starter is not None:
+        changes["mkdocs.yml"] = starter
+    if not workflow_path.exists():
+        changes[WORKFLOW] = files("relcon_docs").joinpath("assets/docs.yml").read_bytes()
+    state = {
+        "schema": 1,
+        "package_version": version("relcon-docs"),
+        "files": {name: digest(content) for name, content in assets.items()},
+    }
+    state_bytes = (json.dumps(state, indent=2, sort_keys=True) + "\n").encode()
+    if not paths[STATE].exists() or paths[STATE].read_bytes() != state_bytes:
+        changes[STATE] = state_bytes
+
+    for name in changes:
+        print(f"Update {name}" if (root / name).exists() else f"Create {name}")
+        if dry_run:
+            path = root / name
+            before = path.read_bytes() if path.exists() else b""
+            print(
+                "".join(
+                    difflib.unified_diff(
+                        before.decode(errors="replace").splitlines(keepends=True),
+                        changes[name].decode().splitlines(keepends=True),
+                        fromfile=f"a/{name}",
+                        tofile=f"b/{name}",
+                    )
+                ),
+                end="",
+            )
+
+    if conflicts:
+        print("Managed-file conflicts: " + ", ".join(conflicts), file=sys.stderr)
+        if not force:
+            print(
+                "No files written. Move customizations to mkdocs.yml or a separate CSS file; "
+                "use --force to replace managed files.",
+                file=sys.stderr,
+            )
+            return 2
+        print("Explicit --force: package contents will replace these managed files.")
+
+    if check:
+        if not changes:
+            print("Configuration is current.")
+        return 1 if changes else 0
+    if dry_run:
+        print("Dry run: no files written.")
+        return 0
+
+    # Validate all destinations before writing anything. Each file replacement
+    # is atomic; the state is written last so an interrupted run can be retried.
+    for name in changes:
+        safe_path(root, name)
+    for name, content in changes.items():
+        atomic_write(root / name, content)
+    print("Configuration updated." if changes else "Configuration is current.")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--version", action="version", version=version("relcon-docs"))
+    commands = parser.add_subparsers(dest="command", required=True)
+    command = commands.add_parser("configure", help="Apply shared documentation defaults")
+    command.add_argument(
+        "--project", type=Path, default=Path.cwd(), help="Project root (default: cwd)"
+    )
+    mode = command.add_mutually_exclusive_group()
+    mode.add_argument("--dry-run", action="store_true", help="Show diffs without writing")
+    mode.add_argument(
+        "--check", action="store_true", help="Exit 1 if updates are needed; do not write"
+    )
+    command.add_argument("--force", action="store_true", help="Replace conflicting managed files")
+    args = parser.parse_args(argv)
+    if args.check and args.force:
+        parser.error("--check cannot be combined with --force")
+    try:
+        return configure(
+            args.project.resolve(), dry_run=args.dry_run, check=args.check, force=args.force
+        )
+    except (ConfigurationError, OSError) as exc:
+        print(f"relcon-docs: {exc}", file=sys.stderr)
+        return 2

relcon_docs-0.1.0.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.5
+Name: relcon-docs
+Version: 0.1.0
+Summary: Shared documentation defaults, styling, and configuration tools for Zensical
+Project-URL: Homepage, https://relaxed-constraints.github.io/relcon-docs/
+Project-URL: Repository, https://github.com/relaxed-constraints/relcon-docs
+Project-URL: Issues, https://github.com/relaxed-constraints/relcon-docs/issues
+Author: Relaxed Constraints
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: mkdocstrings-python>=2.0.10
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: ruff>=0.9
+Requires-Dist: zensical<0.2,>=0.1.1
+Description-Content-Type: text/markdown
+
+# relcon-docs
+
+Shared documentation defaults, styling, and configuration tools for Relaxed Constraints
+projects using Zensical.
+
+Install this package as a **documentation dependency**. It supplies Zensical, the
+Python API handler and formatter, shared modern-theme settings, and copy-button CSS.
+It has no dependency on BONDI or Yanex.
+
+## Install
+
+```sh
+uv add --group docs relcon-docs
+```
+
+Or install with `python -m pip install relcon-docs`. Keep uv.lock committed for
+reproducible builds. Upgrade with `uv lock --upgrade-package relcon-docs`, sync
+the docs group, and run `relcon-docs configure` to refresh shared assets.
+
+## Configure a project
+
+Once installed in your project's environment:
+
+```sh
+relcon-docs configure --dry-run
+relcon-docs configure
+zensical serve
+```
+
+The project directory must already exist. A fresh project gets a minimal
+`mkdocs.yml`; add your Markdown pages under `docs/` and edit navigation as needed.
+The starter uses a localhost `site_url` for previews. Replace it with the published
+site URL before deployment; Markdown exports require this setting.
+For an existing YAML project, add `INHERIT: .relcon-docs/base.yml` first.
+Convert and remove any `zensical.toml` before configuring: Zensical prefers it over YAML.
+
+| File | Owner |
+| --- | --- |
+| `.github/workflows/docs.yml` | Project: deployment triggers and reusable workflow revision |
+| `mkdocs.yml` | Project: metadata, navigation, API paths, Markdown-export sections and overrides |
+| `.relcon-docs/base.yml` | Package: theme, Markdown extensions and API-rendering defaults |
+| `docs/stylesheets/relcon-docs.css` | Package: copy buttons, diagrams and figures |
+| `docs/javascripts/relcon-docs-math.js` | Package: on-demand MathJax rendering |
+| `.relcon-docs/state.json` | Tool: applied version and hashes for detecting manual edits |
+
+Commit these files. Configuration is explicit: installing or upgrading the
+dependency never rewrites project files. Builds and previews use ordinary
+`zensical` commands, without a wrapper or sibling checkout.
+
+## Upgrade and review
+
+Upgrade the dependency and lockfile, then run:
+
+```sh
+relcon-docs configure --dry-run
+relcon-docs configure
+zensical build --strict
+```
+
+Unmodified managed files are updated. A changed or deleted managed file produces a
+conflict and **no files are written**. On first adoption, an existing managed path
+with different contents also conflicts. Identical contents can be adopted safely.
+
+Move customizations into project overrides or a separate stylesheet. To explicitly
+replace conflicting managed files, use `configure --force`; inspect the proposed
+changes first with `configure --dry-run --force`. Force never rewrites an existing
+`mkdocs.yml` or `.github/workflows/docs.yml`. Invalid state files must be restored from Git; force does not bypass
+state validation or symlink protection.
+
+Each file replacement is atomic; the full set is not a filesystem transaction.
+State is written last, and an interrupted run can be retried.
+
+## Project overrides
+
+Mappings merge recursively. Lists replace inherited lists, so repeat the shared
+entries when overriding `theme.features` or `extra_css`. Use mapping syntax for
+plugins and Markdown extensions to preserve unrelated inherited defaults:
+
+```yaml
+INHERIT: .relcon-docs/base.yml
+site_name: My research project
+site_url: https://example.org/my-project/
+plugins:
+  mkdocstrings:
+    handlers:
+      python:
+        paths: [src]
+  llmstxt:
+    sections:
+      Documentation: ["*.md"]
+      API reference: ["reference/**/*.md"]
+```
+
+Markdown exports and `llms.txt` are enabled in the shared defaults for all
+Markdown pages, including nested pages. Existing projects inherit them without
+adding a local plugin configuration. A valid project `site_url` is required.
+
+The shared index uses a `Documentation` section. Section mappings merge during
+inheritance: override `Documentation` to change its page patterns; adding a
+different section name retains the inherited section too. Most projects can omit
+`llmstxt` entirely. Set `plugins.llmstxt.enabled: false` to opt out.
+
+This first version supports the standard `docs/` source directory and direct
+inheritance from `.relcon-docs/base.yml`. It does not migrate arbitrary configurations,
+prune old stylesheets, or modify existing workflow files.
+
+## Callouts, collapsible notes and diagrams
+
+Shared defaults enable `admonition`, `pymdownx.details` and Mermaid fenced
+blocks. Projects do not need local extension configuration for these features.
+For example:
+
+````markdown
+!!! note "Research note"
+
+    Record assumptions beside your results.
+
+??? tip "Show details"
+
+    Put optional explanations here.
+
+```mermaid
+graph LR
+    Data --> Experiment --> Results
+```
+````
+
+Zensical initializes Mermaid on pages containing diagrams. Shared light/dark colours apply to standard flowchart nodes, labels and connectors,
+and sequence actors, messages and notes. Custom diagrams can use the
+`--relcon-diagram-*` CSS properties; legacy `--jb-*` aliases remain supported.
+See the [diagram examples](https://relaxed-constraints.github.io/relcon-docs/diagrams/).
+Project-specific overrides can remain in a separate local stylesheet.
+If overriding `custom_fences`, include the Mermaid entry too: lists replace
+inherited lists.
+
+## GitHub Pages deployment
+
+`configure` creates `.github/workflows/docs.yml` **only when absent**. The starter
+enables manual deployment (`workflow_dispatch`) and includes commented examples
+for pushes to `main` and published releases. After creation the file belongs to the
+project: rerunning configure, including with `--force`, leaves it byte-for-byte
+unchanged. It is not included in the managed-file hashes. A missing starter is
+reported by `--check` and shown by `--dry-run`; ordinary configure recreates it.
+
+The starter calls the shared
+[`deploy-docs.yml`](https://github.com/relaxed-constraints/relcon-docs/blob/main/.github/workflows/deploy-docs.yml)
+workflow. It checks out the **caller repository and triggering revision**, installs
+its locked `docs` dependency group, checks managed configuration, runs a strict
+Zensical build, uploads `site/`, and deploys it to GitHub Pages. It does not update
+configuration during deployment.
+
+Choose the project's policy by editing the starter's `on` mapping. For BONDI,
+keep automatic deployment limited to published releases:
+
+```yaml
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+```
+
+A consumer project can instead publish on each push to `main`:
+
+```yaml
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+```
+
+The caller grants `contents: read`, `pages: write` and `id-token: write`.
+The build job uses read-only repository access; the deployment job gets Pages
+permissions and uses the `github-pages` environment. Deployments share a concurrency
+group and do not cancel an in-progress deployment.
+
+### Repository setup and workflow updates
+
+- Set **Settings → Pages → Source → GitHub Actions** once in each repository.
+- Set the project's `site_url` to its published URL before deploying.
+- Commit `uv.lock`, provide a `docs` dependency group, and use the standard
+  `docs/` source and `site/` output directories.
+- For release deployment, allow the release tags under the `github-pages`
+  environment's deployment protection rules.
+- When an existing deployment workflow uses another name (such as `pages.yml`),
+  consolidate it with the starter before enabling automatic triggers. Configure
+  does not remove or alter other workflows.
+
+The starter references `@main`; use a reviewed full commit SHA for reproducible
+deployment tooling. No `v1` tag is assumed. The workflow revision and Python package
+dependency are independent: upgrading the package never rewrites the caller's
+workflow reference or triggers.
+
+Optional caller job inputs are `python-version` (default `"3.11"`) and
+`uv-version` (default `"0.13.6"`). For example:
+
+```yaml
+jobs:
+  docs:
+    uses: relaxed-constraints/relcon-docs/.github/workflows/deploy-docs.yml@main
+    with:
+      python-version: "3.12"
+```
+
+## CLI reference
+
+`relcon-docs configure [--project PATH] [--dry-run | --check] [--force]`
+
+- `--project`: target an existing project root; defaults to the working directory.
+- `--dry-run`: print proposed file diffs without writing. Conflicts still fail unless forced.
+- `--check`: write nothing; exit 0 when current, 1 for pending updates, 2 for errors/conflicts.
+- `--force`: explicitly replace conflicting managed files; incompatible with `--check`.
+- `relcon-docs --version`: display the installed package version.
+
+Use `relcon-docs configure --check` in CI before `zensical build --strict`.
+
+## Development
+
+```sh
+uv sync --locked
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run relcon-docs configure --check
+uv run zensical build --strict
+uv build
+```
+
+For a local consumer trial before publishing, install the built wheel in an isolated
+environment. The installed package contains all assets; consumers need no checkout
+of this repository.
+
+## Feature examples
+
+The documentation includes walkthroughs for Markdown, Mermaid diagrams, equations
+and figures. Equations use the shared Arithmatex configuration and a pinned
+MathJax renderer loaded from jsDelivr only on pages containing mathematics.
+The site itself uses relcon-docs and its reusable deployment workflow.
+
+### API member defaults
+
+API members are ordered alphabetically. Members whose names start with `_` are
+excluded from automatic member listings, including double-underscore names.
+Projects can override `members_order` and `filters` under
+`plugins.mkdocstrings.handlers.python.options` in `mkdocs.yml`, or on an
+individual API directive when a specific private or special method needs documenting.

relcon_docs-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+relcon_docs/__init__.py,sha256=W0NXnT-yLV2EiR47avbXl4Wc0z0TVreVpty1L55oENs,75
+relcon_docs/cli.py,sha256=9p-VR4ZVCQpyxkqN2VyVFr8Zax_3A5hGE_4L-gJReK4,9201
+relcon_docs/assets/base.yml,sha256=62HfufJqTk2Zjwq-2IP7186KvxLVMfoWE134Ja2uOck,1542
+relcon_docs/assets/docs.yml,sha256=eGpQdIndm2jeVWazXyuRDHZqFgEQxsyVziuxCk5dWCk,624
+relcon_docs/assets/relcon-docs-math.js,sha256=uOexX0GfTlIINXASL1N-pwNrtSklbX8XKq5RRJ1SNmE,1284
+relcon_docs/assets/relcon-docs.css,sha256=r7xrqQrU6A6deb3YmkqCWsL_Yq9MIT0ij2eL6HyBCoU,3520
+relcon_docs-0.1.0.dist-info/METADATA,sha256=RVken39weXKGH7djUsVHlsoJVsSauUbD6tZ1Btb_YtI,10364
+relcon_docs-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+relcon_docs-0.1.0.dist-info/entry_points.txt,sha256=ay_WbSM4YntoyOebqfHlmKovXjpjX5TEauCAmoK_xoo,53
+relcon_docs-0.1.0.dist-info/licenses/LICENSE,sha256=YboKyi6DcoknxJ9-nAyx50FWQP1Bi7fpBbDGP8IZRcc,1076
+relcon_docs-0.1.0.dist-info/RECORD,,

relcon_docs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

relcon_docs-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+relcon-docs = relcon_docs.cli:main

relcon_docs-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Relaxed Constraints
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.