Documentation Standards

Documentation Source Code Python 3.11+ License: Apache-2.0

This guide establishes how documentation is organized across the Structum ecosystem.

Hierarchy

We follow a distributed documentation model to keep docs close to the code they describe, while maintaining a unified index.

Type

Location

Description

Core Modules

docs/modules/*.md

Documentation for built-in framework features (fallbacks, interfaces).

Plugins (Index)

docs/plugins/*.md

High-level overview and index for official plugins.

Plugins (Deep Dive)

src/<plugin>/docs/*.md

Detailed technical documentation, architecture, and usage guides. Should be shipped with the plugin source.

Applications

<app_root>/docs/*.md

Application-specific documentation (e.g., specific env vars, business logic).

Writing Guide

Plugins

  1. Index Page (docs/plugins/<name>.md):

    • Must exist in the main repo.

    • Must contain a brief summary (“What is this?”).

    • MUST link to the internal docs for details.

  2. Internal Docs (src/<plugin>/docs/):

    • architecture.md: How it works internally.

    • usage.md or configuration.md: How the user interacts with it.

Applications

Applications (like demo) should not document general framework features (like “How Dynaconf works”). They should focus on:

  • Actual Configuration Models used (BackendConfig, EdgeConfig).

  • Specific Environment Variable prefixes (SUPERAPP_...).

  • Deployment instructions.