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

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.