Documentation Specialist

Template structure:

def function_name(param1: type1, param2: type2 = default) -> return_type:
    """
    Brief one-line summary.
    
    Longer description explaining behavior, edge cases, or important
    notes about the function.
    
    Args:
        param1: Description of param1
            Additional details if needed (indent 4 spaces)
        param2: Description of param2 (default: value)
    
    Returns:
        Description of return value
    
    Raises:
        ExceptionType: When this exception occurs
    
    Example:
        >>> result = function_name("test", param2=10)
        >>> print(result)
        expected output
    
    Note:
        Any important notes or warnings
    """

Writing Class Docstrings

1. Class-level docstring: Purpose, attributes, usage patterns
2. Constructor docstring: Parameters and initialization details
3. Method docstrings: Follow same format as functions
4. Include usage examples: Both decorator and direct usage patterns

See docstring_examples.md for complete class examples.

Creating README Files

1. Use README template: Load assets/templates/readme_template.md
2. Fill required sections:
   • Project name and brief description
   • Features list
   • Installation instructions
   • Quick start example
   • Usage examples (basic and advanced)
3. Add optional sections as needed:
   • Configuration
   • API reference links
   • Contributing guidelines
   • License
4. Test all code examples: Ensure they work before including

Writing API Documentation

1. Load API template: Use assets/templates/api_reference_template.md
2. Document each function/class:
   • Signature with type hints
   • Parameter descriptions
   • Return value details
   • Raised exceptions
   • Working example
3. Organize by module: Group related functions together
4. Include navigation: Table of contents for large APIs

Creating Tutorial Guides

1. Load tutorial template: Use assets/templates/tutorial_template.md
2. Structure content:
   • Introduction (what they'll learn)
   • Prerequisites
   • Step-by-step instructions
   • Expected outputs after each step
   • Common issues and solutions
   • Next steps
3. Test tutorial: Follow your own steps to verify accuracy
4. Include troubleshooting: Address common problems

Maintaining Changelogs

1. Load CHANGELOG template: Use assets/templates/changelog_template.md
2. Follow Keep a Changelog format:
   • Group changes by type (Added, Changed, Deprecated, Removed, Fixed, Security)
   • Include version numbers and dates
   • Keep Unreleased section at top
3. Write clear descriptions: What changed and why it matters to users

Adding Code Comments

Comment guidelines:

• Explain WHY, not WHAT (code shows what)
• Document complex algorithms or non-obvious logic
• Explain workarounds or hacks
• Add context for future maintainers
• Avoid obvious comments

Good comment examples:

# RSI calculation requires at least 'period' data points
# to establish initial average gain/loss
if len(prices) < period:
    return None

# yfinance sometimes returns data in wrong timezone
# Must explicitly convert to UTC before saving
data.index = data.index.tz_convert('UTC')

Code Change Documentation Update

Trigger this workflow whenever .py files are created or modified as part of a code change task.

1. Identify changed .py files: Collect the list of new and modified Python files from the current task.
2. Detect changed public symbols: For each file, identify:
   • New public functions or classes (no leading underscore)
   • Modified public functions or classes (signature changed, body changed)
   • Deleted public functions or classes
3. Update inline docstrings: For every new or modified public function and class, write or update a Google-style docstring following the templates in this skill. Do not add docstrings to private symbols (_name) unless explicitly asked.
4. Update README if public interface changed: If any public function or class was added, removed, or had its signature changed, locate the relevant section in the module or project README and update it. If no README section covers the changed symbol, add one.
5. Append CHANGELOG entry: Load assets/templates/changelog_template.md. Append a new entry under [Unreleased] grouping changes by type: Added / Changed / Removed. One line per changed symbol — state what changed and why it matters to callers.
6. Log all documentation file changes: After updating docstrings, README, and CHANGELOG, invoke the agent-logging skill to log each file that was modified.

Scope rules:

• Docstrings: update only the files that changed — do not sweep unrelated files
• README: update only sections directly related to the changed public interface
• CHANGELOG: one entry per code-change task, not one entry per file

Examples

Example 1: Adding Docstring to Data Fetching Function

Input: "Add docstring to this function that fetches stock data"

Process:

1. Identify function signature and parameters
2. Understand what the function does
3. Apply Google-style docstring template
4. Add example with real ticker
5. Document possible exceptions

Output:

def fetch_stock_data(ticker: str, period: str = "1y") -> pd.DataFrame:
    """
    Fetch historical stock price data from Yahoo Finance.
    
    Args:
        ticker: Stock ticker symbol (e.g., "AAPL", "MSFT")
        period: Time period for data (default: "1y")
            Valid periods: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max
    
    Returns:
        DataFrame with columns: Date, Open, High, Low, Close, Volume
        Index is datetime, timezone-aware (UTC)
    
    Raises:
        ValueError: If ticker is invalid or empty
        DataFetchError: If API request fails after retries
    
    Example:
        >>> data = fetch_stock_data("AAPL", period="6mo")
        >>> print(data.head())
                       Open    High     Low   Close      Volume
        2023-07-01  180.00  182.50  179.50  182.00  50000000
    
    Note:
        Data is fetched from Yahoo Finance and may have slight delays.
        Historical data older than 10 years may be incomplete.
    """

Example 2: Creating Project README

Input: "Create README for my stock analysis project"

Process:

1. Load assets/templates/readme_template.md
2. Fill in project-specific information
3. Add installation instructions
4. Include quick start example
5. Add usage examples for key features
6. Test all code examples

Output: Complete README.md with:

• Clear project description
• Installation steps tested and verified
• Quick start example that runs
• Usage examples for main features
• Links to detailed documentation

Example 3: Documenting API Response Capture Class

Input: "Document the ResponseCapturer class with all methods"

Process:

1. Write class-level docstring explaining purpose
2. Document constructor parameters
3. Add docstrings to all public methods
4. Include usage examples (decorator and context manager)
5. Document all raised exceptions

Output: Fully documented class with:

• Class description and attributes
• Constructor documentation
• Method docstrings with examples
• Usage patterns demonstrated
• Exception documentation

Style Guidelines

Docstring Best Practices

• Use present tense ("Returns" not "Will return")
• Start with verb for functions ("Fetch", "Calculate", "Parse")
• Start with noun for classes ("Handler for", "Manager that")
• Keep first line under 80 characters
• Use complete sentences with proper punctuation
• Include type hints in signature, not docstring (Python 3.8+)

README Best Practices

• Lead with what the project does (not what it is)
• Show code before explaining it
• Use relative links for internal docs
• Keep quick start under 10 lines of code
• Test all examples before publishing

Code Comment Best Practices

• Place comments above the code they describe
• Use # for single-line, """ for multi-line
• Don't comment obvious code
• Update comments when code changes
• Remove commented-out code (use version control)

Advanced Features

Module Docstrings

For module-level documentation including attributes and examples, see docstring_examples.md.

Changelog Conventions

For semantic versioning and changelog best practices, see changelog_guide.md.

Reference Materials

• Style Guide: style_guide.md - Complete style conventions
• Docstring Examples: docstring_examples.md - Comprehensive examples
• Changelog Guide: changelog_guide.md - Version management
• Templates: All templates available in assets/templates/