Metadata-Version: 2.4
Name: irminsul
Version: 0.1.0.dev0
Summary: A documentation system for complex codebases. Enforces structural invariants in CI.
Project-URL: Homepage, https://github.com/huajie-zhong/irminsul
Project-URL: Repository, https://github.com/huajie-zhong/irminsul
Project-URL: Issues, https://github.com/huajie-zhong/irminsul/issues
Author: Irminsul authors
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: ci,docs,documentation,linter,mkdocs
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: gitpython>=3.1
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: litellm>=1.40
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: pathspec>=0.12
Requires-Dist: pydantic>=2.7
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocs>=1.6; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: mkdocs
Requires-Dist: mkdocs-material>=9.5; extra == 'mkdocs'
Requires-Dist: mkdocs>=1.6; extra == 'mkdocs'
Description-Content-Type: text/markdown

# Irminsul

> A documentation system for complex codebases. Designed to resist rot, scale with complexity, and survive philosophy shifts.

Irminsul is a Python CLI + composite GitHub Action that enforces structural invariants on your `/docs` tree in CI. The rules are simple: every fact has one home, every doc has one purpose, every cross-reference is bidirectional and machine-verifiable. The tool's job is to make sure those rules stay true while the codebase evolves.

## Quickstart

```bash
pipx install irminsul
cd my-codebase
irminsul init
```

That scaffolds a 9-layer `/docs` skeleton, an `irminsul.toml` config, GitHub Actions workflows, and pre-commit hooks. Three commands, ten seconds, fully wired.

## What it checks

Hard, blocking checks (deterministic, no LLM):

- **Frontmatter validity** — required fields present, enums valid, IDs match filenames
- **Glob resolution** — every `describes` glob resolves to ≥1 source file
- **Coverage uniqueness** — every source file is claimed by exactly one most-specific doc
- **Internal link integrity** — no broken `[link](other.md)` references
- **Schema-leak detection** — no class/type definitions in component docs (those belong in the generated reference layer)

## CI integration

```yaml
on: pull_request
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: <github-user>/irminsul@v0.1.0
        with:
          scope: hard
```

`irminsul init` writes this file for you.

## License

AGPL-3.0-or-later. See [`LICENSE`](LICENSE).

## Reference

The full architectural reference for the doc system Irminsul enforces lives in [`docs/90-meta/doc-system.md`](docs/90-meta/doc-system.md).
