Documentation Rules

Standards for comprehensive and consistent documentation throughout the project.

File: documentation-rules.mdc

Purpose

The Documentation Rules establish standards for creating and maintaining comprehensive documentation across the project. These rules ensure consistency, completeness, and clarity in all documentation, from code comments to user guides.

Key Principles

  • Comprehensive Coverage: Documentation for all aspects of the project

  • Consistent Format: Standard formats for different types of documentation

  • Clear Structure: Logical organization of documentation materials

  • Up-to-Date Content: Regular updates to match code changes

  • User Focus: Documentation targeted to appropriate audiences

Detailed Contents

Documentation Structure

Guidelines for organizing documentation:

  • Use of Sphinx for documentation generation

  • Logical sectioning of documentation

  • Cross-referencing between related sections

  • Diagrams for complex components

  • Directory-based organization

  • reStructuredText directives for enhanced features

  • API reference generation from docstrings

Module-Level Documentation

Requirements for module documentation:

  • Module-level docstrings at the beginning of each file

  • Purpose statement at the start

  • Feature list in numbered format

  • Usage examples where appropriate

  • Documentation of design patterns used

  • Listing of main classes/functions in the module

Class-Level Documentation

Standards for class documentation:

  • Clear purpose and responsibility explanation

  • Design pattern implementation documentation

  • Key attribute listings with descriptions

  • Inheritance relationship documentation

  • Usage examples for complex classes

  • Performance consideration notes

Method-Level Documentation

Requirements for method documentation:

  • Clear statement of method purpose

  • Explanation of implementation approach

  • NumPy-style parameter documentation

  • Return value documentation

  • Exception documentation

  • Usage examples for complex methods

Docstring Format

Standardized docstring format:

  • Brief purpose description

  • Step-by-step explanation of functionality

  • Parameter documentation with types

  • Return value documentation with types

  • Proper indentation and formatting

  • Full sentences with punctuation

Style Guidelines

Documentation style standards:

  • Consistent indentation in docstrings

  • 80-character line length limit

  • Full sentences with proper punctuation

  • Specific, not vague descriptions

  • Documentation updates with code changes

  • Code formatting for code references

What vs How Documentation

Balance between different documentation types:

  • Explanation of both what a component does and how it works

  • Focus on intent and design decisions

  • Implementation approach explanation

Documentation Files

Standard documentation files:

  • README.md for project overview

  • CONTRIBUTING.md for contribution guidelines

  • IMPLEMENTATION_PLAN.md for detailed status

  • docs/ directory for Sphinx documentation

  • API reference documentation

  • User and developer guides

Sphinx Documentation Management

Guidelines for Sphinx documentation:

  • When to build documentation

  • Build process steps

  • Error and warning resolution

  • Documentation verification process

  • Link and reference checking

Diagram Generation

Standards for architecture diagrams:

  • System architecture diagrams

  • Component relationship diagrams

  • Data flow diagrams

  • Generation approach using Python with PIL

  • Output location and naming conventions

Rationale

The documentation rules serve several essential purposes:

  1. Knowledge Transfer: Facilitating understanding of the codebase

  2. Maintenance Support: Making it easier to maintain and modify code

  3. Onboarding: Helping new developers get up to speed

  4. Quality Assurance: Ensuring consistency and completeness in documentation

  5. User Support: Providing clear information for users and stakeholders

By following these documentation rules, developers can create clear, comprehensive, and consistent documentation that supports both development and use of the software.