relcon-docs 0.1.0__tar.gz

relcon_docs-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+permissions:
+  contents: read
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+      - run: uv sync --locked
+      - run: uv run pytest
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run relcon-docs configure --check
+      - run: uv run zensical build --strict
+      - run: uv build
+      - name: Verify installed wheel outside checkout
+        shell: bash
+        run: |
+          uv venv /tmp/relcon-docs-wheel
+          uv pip install --python /tmp/relcon-docs-wheel/bin/python dist/*.whl
+          mkdir -p /tmp/relcon-docs-example/docs
+          cd /tmp/relcon-docs-example
+          /tmp/relcon-docs-wheel/bin/relcon-docs configure
+          test -f .github/workflows/docs.yml
+          /tmp/relcon-docs-wheel/bin/relcon-docs configure --check
+          echo '# Wheel smoke test' > docs/index.md
+          /tmp/relcon-docs-wheel/bin/zensical build --strict

relcon_docs-0.1.0/.github/workflows/deploy-docs.yml

@@ -0,0 +1,51 @@
+name: Deploy documentation
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        description: Python version used to build the caller's documentation
+        type: string
+        default: "3.11"
+      uv-version:
+        description: uv version used to install the caller's locked docs dependencies
+        type: string
+        default: "0.13.6"
+
+permissions:
+  contents: read
+
+# Serialize Pages deployments in the caller repository, including releases.
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          version: ${{ inputs.uv-version }}
+          python-version: ${{ inputs.python-version }}
+      - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+      - run: uv sync --locked --group docs
+      - run: uv run --group docs relcon-docs configure --check
+      - run: uv run --group docs zensical build --strict
+      - uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
+        with:
+          path: site
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
+        id: deployment

relcon_docs-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,18 @@
+# This repository uses its own reusable workflow from the same revision.
+name: Deploy documentation
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  checks:
+    uses: ./.github/workflows/ci.yml
+  docs:
+    needs: checks
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    uses: ./.github/workflows/deploy-docs.yml

relcon_docs-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+permissions:
+  contents: read
+concurrency:
+  group: pypi-release
+  cancel-in-progress: false
+jobs:
+  checks:
+    uses: ./.github/workflows/ci.yml
+  build:
+    needs: checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e
+        with:
+          version: "0.13.6"
+          python-version: "3.11"
+      - name: Validate release tag
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          uv run --no-project python -c "import os, tomllib; version = tomllib.load(open('pyproject.toml', 'rb'))['project']['version']; assert os.environ['RELEASE_TAG'] == 'v' + version, 'Release tag must match package version'"
+      - run: uv build
+      - run: uvx --from twine twine check --strict dist/*
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: distributions
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/relcon-docs
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086

relcon_docs-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.cache/
+site/
+dist/
+*.egg-info/

relcon_docs-0.1.0/.relcon-docs/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-0.1.0/.relcon-docs/state.json

@@ -0,0 +1,9 @@
+{
+  "files": {
+    ".relcon-docs/base.yml": "eb61dfb9f26a4e4d998f0abed883fbd7ce8abf12d531fa16135df825adae39c9",
+    "docs/javascripts/relcon-docs-math.js": "b8e7b15f419f4e52083570122f537ea7036bb529256d7f172aae51449d523661",
+    "docs/stylesheets/relcon-docs.css": "afbc6ba90ad4e80e9d79bdd89a4a825ac2ff62af4c213d228f678be87c810a85"
+  },
+  "package_version": "0.1.0",
+  "schema": 1
+}

relcon_docs-0.1.0/AGENTS.md

@@ -0,0 +1,12 @@
+# Working on relcon-docs
+
+Keep this package independent of BONDI and Yanex. Shared documentation configuration
+and assets belong here; project content and research code do not.
+
+Preserve ordinary Zensical build and serve commands. Configuration updates are explicit.
+Never overwrite project-owned configuration. Treat managed-file conflicts as errors
+unless the caller explicitly requests force.
+
+Use uv, pytest and Ruff. Test configuration updates, conflicts, installed assets and
+strict documentation builds. Record user-facing changes under Unreleased.
+Work on codex/ branches and leave commits for review; do not merge without approval.

relcon_docs-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 — 2026-11-15
+
+- Enable heading permalinks with the paragraph symbol and descriptive link titles.
+
+- Sort API members alphabetically and exclude underscore-prefixed members by default.
+
+- Publish the self-hosted documentation showcase with Markdown, diagrams, equations
+  and figures; use the reusable deployment workflow on main and manual runs.
+- Add shared on-demand MathJax rendering and dark-theme Markdown-copy controls.
+
+- Add paired accent fill, border and text colours for highlighting diagram boxes,
+  with a light/dark example on the diagram-colours page.
+
+- Share accessible light/dark diagram colours for flowcharts and sequence roles,
+  with CSS properties for custom diagrams and legacy variable aliases.
+
+- Enable callouts, collapsible notes and Mermaid diagrams in shared defaults.
+
+- Enable Markdown exports and llms.txt in shared defaults for new and existing
+  projects, without requiring local plugin configuration.
+
+- Add a reusable GitHub Pages deployment workflow with caller-owned triggers.
+- Create a manual-only starter docs.yml on configuration when absent; preserve
+  existing workflow contents, even with --force.
+
+- Add packaged Zensical defaults and copy-button styling.
+- Add explicit configuration, dry-run diffs, CI checks and managed-file conflict detection.
+- Preserve project-owned YAML and support ordinary Zensical builds and previews.

relcon_docs-0.1.0/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.

relcon_docs-0.1.0/PKG-INFO

@@ -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.