112 lines
4.8 KiB
Markdown
112 lines
4.8 KiB
Markdown
# govoplan-docs
|
|
|
|
<!-- govoplan-repository-type:start -->
|
|
**Repository type:** module (platform).
|
|
<!-- govoplan-repository-type:end -->
|
|
|
|
GovOPlaN Docs provides the documentation layer for configured GovOPlaN systems.
|
|
|
|
It answers "what does this installation provide for me?" before it answers "what could the full product do?". The goal is to reduce documentation complexity by starting from installed modules, enabled configuration, tenant policy, role, route availability, and visible capabilities.
|
|
|
|
## Ownership
|
|
|
|
This repository owns:
|
|
|
|
- backend module manifest `docs`
|
|
- configured-system documentation indexing
|
|
- documentation source and contribution contracts
|
|
- role-aware and tenant-aware documentation filtering
|
|
- evidence pages for disabled, unavailable, or optional capabilities
|
|
- documentation route contributions and future WebUI package `@govoplan/docs-webui`
|
|
- documentation sync/import tooling that belongs to the runtime docs layer rather than the repository maintenance scripts
|
|
|
|
Core owns module discovery, configuration package loading, route registry, RBAC evaluation, capability registry, and shared WebUI shell behavior.
|
|
|
|
While Docs is installed, its managed `docs_reader` tenant role is an automatic
|
|
authenticated-member baseline. Access derives its narrow read grant from the
|
|
active Docs manifest without per-user assignments or authorization-time writes,
|
|
so ordinary users can open their configured handbook without an administrator
|
|
assigning documentation access one account at a time.
|
|
Administrative documentation remains separately protected by
|
|
`docs:documentation:admin` or the applicable administration scope.
|
|
|
|
## Documentation model
|
|
|
|
The docs module should render documentation in three layers:
|
|
|
|
- Configured: installed and enabled behavior that applies to the current tenant, organization, role, or route.
|
|
- Available: installed but disabled or hidden behavior that can be enabled by configuration or permission.
|
|
- Evidence: referenced capabilities, modules, examples, or product documentation that explain what else may be possible without making it the primary reading path.
|
|
|
|
## Module integration
|
|
|
|
Backend entry point:
|
|
|
|
```toml
|
|
[project.entry-points."govoplan.modules"]
|
|
docs = "govoplan_docs.backend.manifest:get_manifest"
|
|
```
|
|
|
|
Frontend package:
|
|
|
|
```text
|
|
@govoplan/docs-webui
|
|
```
|
|
|
|
Platform module manifests, configuration packages, release catalogs, and governance rules are documented in `govoplan-core/docs/`.
|
|
|
|
Every module manifest must contribute a static documentation baseline for both
|
|
the `user` and `admin` projections through `ModuleManifest.documentation`.
|
|
Runtime providers may add actor- and configuration-specific detail, but they do
|
|
not replace that baseline. A behavior change is complete only when the owning
|
|
module updates the affected workflows, settings, permissions, limitations, and
|
|
operational consequences. Validate workspace coverage with:
|
|
|
|
```sh
|
|
cd /mnt/DATA/git/govoplan
|
|
./tools/checks/check-manifest-shapes.py
|
|
```
|
|
|
|
Feature content remains in the owning module. Docs indexes and renders the
|
|
contributions without importing feature implementations.
|
|
|
|
Capabilities can provide generic documentation without exposing their runtime
|
|
provider implementation:
|
|
|
|
```python
|
|
ModuleManifest(
|
|
capability_factories={"example.lookup": build_lookup},
|
|
capability_documentation={
|
|
"example.lookup": CapabilityDocumentation(
|
|
label="Example lookup",
|
|
summary="Resolves records through the versioned lookup contract.",
|
|
contract_version="2",
|
|
stability="stable",
|
|
audience=("module_admin",),
|
|
),
|
|
},
|
|
)
|
|
```
|
|
|
|
Docs also projects the configured module release catalog and configuration
|
|
package catalog through the public Core catalog contracts. Catalog trust,
|
|
freshness, provenance, descriptions, and package requirements remain visible
|
|
as typed evidence; provider objects, credentials, and secret configuration are
|
|
never imported into the Docs WebUI.
|
|
|
|
Module-owned external-provider runtime state is also projected through the
|
|
Core contract. Administrative documentation may show sanitized binding-level
|
|
state; ordinary-user documentation receives only aggregate configured, active,
|
|
authority, health, freshness, conflict, recovery, and observation fields.
|
|
URLs, credential references, provider error text, and binding identifiers are
|
|
excluded from the user projection.
|
|
|
|
## Concept documents
|
|
|
|
- `docs/DOCUMENTATION_LAYER_CONCEPT.md` defines the configured, available, and evidence documentation model.
|
|
- `docs/INSTANCE_AWARE_DOCUMENTATION.md` defines the runtime context and condition model.
|
|
- `docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md` defines the workflow, structure/reference, and design-pattern documentation experience.
|
|
- Core's `DocumentationHelpLink` is the stable route/field/blocker entry point
|
|
into a topic or help context, with hosted fallback when this module is not
|
|
active.
|