Documentation Standards & Authoring¶

Authoring with Org-mode¶

We use orgmode as our primary authoring format. It provides a structured environment for capturing technical notes, code snippets, and mathematical notation.

Syntax Reference: If you are new to Org-mode, consult the Org Mode Manual for basic syntax.
Definition Lists :: Use the format: ~- Term: Definition~.
Source Blocks: Use #+BEGIN_SRC blocks for code samples.

Documentation Framework¶

While the Diátaxis framework informs the content categories, we organize the physical files as follows:

Root: High-level project state like index.org, changelog.org, devnotes.org.
Contributing: Logistical guides for developers like contributing/index.org, test_requirements.org.
Tools: Practical tool documentation organized by submodule like tools/eon/, tools/geom/.

Writing Style¶

To ensure the build pipeline handles your contribution correctly, follow these authoring rules:

Command Line Reference: Use the .. click:: directive inside a #+BEGIN_EXPORT rst block to automatically generate CLI documentation.
External References: Use the @@rst::...@@ syntax for specific intersphinx links (e.g., pointing to the eOn schema).
Source Code Links: Link to the internal API reference using @@rst::mod:`rgpycrumbs.path.to.module`@@.

Content Structure Template for Tools¶

Every new tool documentation should follow this approximate structure:

Title: A clear heading for the tool.
CLI Export: The click directive for automated help output.
Usage: A #+BEGIN_SRC shell block showing a real-world example.
Integration: Context on how the tool interacts with external software (e.g., eOn config snippets).
API Reference: A link to the developer source documentation.

Verifying Changes¶

While the build happens automatically, you should verify the rendered output to ensure your Org-mode syntax translates correctly to Sphinx.

Pull Request Previews¶

Every Pull Request triggers an automated build. Once completed, a bot posts a comment with a link to a live preview.

Review checklist: You must check this preview before requesting a review. Pay close attention to cross-references and table rendering.

Local Build¶

If you need to verify changes locally before pushing:

pixi run r docbld

Outputs to docs/build/, served with:

python -m http.server -d docs/build
# visit localhost:8000 in the browser

For a clean rebuild:

pixi run r docdel

README and Branch Structure¶

The README.md is generated from readme_src.org via Emacs batch export.

Pre-commit hook: A prek hook (gen-readme) regenerates README.md whenever readme_src.org is staged. Requires emacs; skips silently if unavailable.
CI workflow: The Generate README workflow pushes the rendered README.md and branding/ assets to the orphan readme branch on every push to main that touches readme_src.org.
Authoritative copy: The readme branch is the GitHub default and always holds the latest rendered README. The copy on main is a local convenience; the readme branch is the source of truth for what GitHub displays.

All source code and development happens on main. The readme branch should never be edited directly.

Release notes and changelog¶

The changelog entries stem from newsfragments handled by towncrier.

News fragments¶

Every Pull Request must include a news fragment. These small text files in markdown format, within docs/newsfragments/ describe the changes for the final user.

Creating a Fragment¶

We recommend uvx to generate a fragment. This ensures the use of the correct tool version without polluting the local environment.

uvx towncrier create -c "Refactored internal import helper to use importlib." +core.fixed

Fragment Categories¶

The system recognizes specific keywords to organize the changelog:

+added: New features or tools.
+fixed: Bug resolutions.
+changed: Modifications to existing logic.
+dev: Internal developer-facing updates.
+security, +removed, +deprecated: Specific lifecycle updates.