docs(site): make docs/ buildable as a documentation site
Adds an mkdocs.yml, a landing page, and `task docs:site` / `task docs:serve`. Deliberately hosting-agnostic: MkDocs is the same input Backstage TechDocs consumes, so choosing where this lands later costs nothing. exclude_docs holds back four subtrees, since everything under docs/ would otherwise be published. archive/ is superseded design and would compete with the current architecture for a reader's attention; inspiration/ discusses other products by name; prds/ are open decisions rather than settled design; github-token.md is credential setup. One PRD is let back through because architecture/migration-decisions.md links to it three times, and a page excluded out from under a live link is just a 404 with extra steps. No nav block. MkDocs derives it from the directory layout, so a new page under docs/architecture/ publishes without a second edit, and there is no hand-maintained tree to drift against the repository. Builds --strict, so a dead internal link fails rather than ships.
This commit is contained in:
1 parent
38c0e485bc
commit
dcaa98cc44
4 files changed
+120
No files matched your search
@@ -48,3 +48,6 @@ config.production.toml
|
||||
.local/
|
||||
__pycache__/
|
||||
*.pyc
|
||||
|
||||
# MkDocs build output (task docs:site)
|
||||
/site/
|
||||
@@ -129,6 +129,23 @@ tasks:
|
||||
happily report last week's tree against today's code.
|
||||
cmds:
|
||||
- python3 tools/reachaudit/reachaudit.py --repo . {{.CLI_ARGS}}
|
||||
docs:site:
|
||||
desc: "Build the documentation site into ./site (MkDocs). --strict, so a dead internal link fails the build."
|
||||
summary: |
|
||||
Publishes docs/ minus the subtrees held back in mkdocs.yml's
|
||||
exclude_docs. Requires mkdocs-material:
|
||||
|
||||
pip install --user mkdocs-material
|
||||
|
||||
Distinct from docs:check, which verifies the generated contract data
|
||||
rather than the site.
|
||||
cmds:
|
||||
- mkdocs build --strict
|
||||
|
||||
docs:serve:
|
||||
desc: "Serve the documentation site locally with live reload on :8000."
|
||||
cmds:
|
||||
- mkdocs serve
|
||||
|
||||
ui:deps:
|
||||
desc: Install the dashboard's node dependencies (ui/node_modules is gitignored)
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# Archie
|
||||
|
||||
Event Driven Agentic Automation.
|
||||
|
||||
**archied** is a resident daemon. It polls a forge (GitHub, Gitea) for issues
|
||||
assigned or labelled to it, works each one in an isolated git worktree through a
|
||||
routed workflow, and opens a pull request for human review.
|
||||
|
||||
It is not a chat wrapper around a repository. Work arrives as events, each task
|
||||
runs in its own sandbox with its own credentials, and the model never runs git.
|
||||
|
||||
## Start here
|
||||
|
||||
- [First playbook](guides/first-playbook.md) walks through getting one piece of
|
||||
work from an issue to a pull request.
|
||||
- [Architecture](architecture/index.md) is the authority for settled design:
|
||||
the package map, the workflow engine, the task lifecycle, and the invariants
|
||||
that hold the whole thing together.
|
||||
|
||||
## What runs where
|
||||
|
||||
A deployment is one daemon plus the processes it talks to. The State Store is a
|
||||
standalone process and owns the database outright; the daemon and gateway never
|
||||
open it directly. Agents execute in containers that receive a task-scoped
|
||||
credential, issued per task and revoked when the worktree is handed back.
|
||||
|
||||
Configuration lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`.
|
||||
Nothing in a working tree is load-bearing at runtime.
|
||||
|
||||
## A note on these docs
|
||||
|
||||
This site is generated from the `docs/` directory of the
|
||||
[archie-core repository](https://github.com/samcharles93/archie-core) on every
|
||||
change to `main`. The repository is the source; this site is a view of it. If
|
||||
the two ever disagree, the repository is right.
|
||||
+65
@@ -0,0 +1,65 @@
|
||||
site_name: Archie
|
||||
site_description: Event Driven Agentic Automation
|
||||
site_url: https://docs.offloaded.dev/
|
||||
repo_url: https://github.com/samcharles93/archie-core
|
||||
edit_uri: edit/main/docs/
|
||||
copyright: Vectis Labs
|
||||
|
||||
# Everything under docs/ is published to the public internet. These subtrees are
|
||||
# held back deliberately, each for its own reason:
|
||||
# archive/ superseded design. Publishing it competes with the current
|
||||
# architecture for a reader's attention, which is the exact
|
||||
# failure this repo already fights.
|
||||
# inspiration/ research notes that discuss other products by name.
|
||||
# prds/ open design decisions, not settled architecture.
|
||||
# github-token setup notes about credentials.
|
||||
# Widen this by deleting a line; nothing else needs to change.
|
||||
exclude_docs: |
|
||||
archive/
|
||||
inspiration/
|
||||
prds/*
|
||||
!prds/ui-service-boundary.md
|
||||
github-token.md
|
||||
|
||||
theme:
|
||||
name: material
|
||||
favicon: public/favicon.svg
|
||||
features:
|
||||
- navigation.sections
|
||||
- navigation.top
|
||||
- navigation.instant
|
||||
- content.code.copy
|
||||
- content.action.edit
|
||||
- search.suggest
|
||||
- toc.follow
|
||||
palette:
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
scheme: default
|
||||
toggle:
|
||||
icon: material/weather-night
|
||||
name: Dark mode
|
||||
- media: "(prefers-color-scheme: dark)"
|
||||
scheme: slate
|
||||
toggle:
|
||||
icon: material/weather-sunny
|
||||
name: Light mode
|
||||
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- attr_list
|
||||
- tables
|
||||
- toc:
|
||||
permalink: true
|
||||
- pymdownx.details
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.superfences
|
||||
|
||||
plugins:
|
||||
- search
|
||||
|
||||
# No nav block on purpose. MkDocs derives the tree from the directory layout, so
|
||||
# adding a page under docs/architecture/ publishes it without a second edit here.
|
||||
# A hand-maintained nav is one more thing that goes stale against 600 commits a
|
||||
# month.
|
||||
Reference in new issue
Block a user