cognitive/docs/guides/package_documentation.md

Package Documentation Guide

Overview

This guide outlines the documentation standards and organization for the Cognitive Modeling package. It combines Python docstrings, markdown documentation, and Obsidian's knowledge management capabilities.

Documentation Structure

Directory Organization

docs/
├── api/              # API reference documentation
├── concepts/         # Core theoretical concepts
├── examples/         # Usage examples and tutorials
├── guides/           # How-to guides and tutorials
└── tools/           # Tool-specific documentation

Documentation Types

1. API Documentation

• Located in docs/api/
• Generated from docstrings
• Follows Google docstring format

Example:

def update_beliefs(observation: np.ndarray, prior: np.ndarray) -> np.ndarray:
    """Updates agent beliefs based on new observations.
    
    Args:
        observation (np.ndarray): Current observation vector
        prior (np.ndarray): Prior belief state
        
    Returns:
        np.ndarray: Updated belief state
        
    See Also:
        [[belief_update_algorithm]]
        [[free_energy_computation]]
    """
    pass

2. Concept Documentation

• Located in docs/concepts/
• Theoretical foundations
• Mathematical formulations
• Links to implementations

Example: concepts/free_energy.md:

# Free Energy Principle

## Mathematical Foundation
...

## Implementation
See [[free_energy_impl]] for code implementation.

3. Example Documentation

• Located in docs/examples/
• Practical usage examples
• Step-by-step tutorials
• Interactive notebooks

Documentation Standards

Python Docstrings

1. Use Google style docstrings
2. Include type hints
3. Link to relevant documentation
4. Provide usage examples

Markdown Files

1. Clear headings hierarchy
2. Consistent formatting
3. Proper linking
4. Code examples

YAML Frontmatter

---
title: Package Documentation
category: guide
status: stable
related:
  - [[docstring_guide]]
  - [[api_reference]]
tags:
  - documentation
  - standards
---

Integration Patterns

Code-to-Doc Links

# Implementation of algorithm described in [[algorithm_spec]]
class BeliefUpdater:
    pass

Doc-to-Code Links

See implementation in `src/models/belief_update.py`:
[[belief_update_impl#update_method]]

Test Documentation

def test_belief_update():
    """Test case described in [[belief_update_tests]]"""
    pass

Maintenance

Documentation Updates

1. Keep in sync with code
2. Update related documents
3. Maintain version consistency
4. Review broken links

Version Control

1. Document version dependencies
2. Track breaking changes
3. Maintain changelog
4. Update migration guides

Tools and Automation

Documentation Generation

• Use sphinx for API docs
• Auto-generate from docstrings
• Maintain cross-references
• Update graphs

Quality Checks

• Link validation
• Style consistency
• Coverage metrics
• Reference integrity

Best Practices

Writing Style

1. Clear and concise
2. Consistent terminology
3. Proper citations
4. Progressive disclosure

Organization

1. Logical grouping
2. Clear navigation
3. Proper linking
4. Version management

Code Examples

1. Runnable snippets
2. Clear context
3. Error handling
4. Best practices

Related Guides

• api_documentation
• docstring_standards
• example_writing
• documentation_workflow

References

• python_documentation
• sphinx_usage
• obsidian_integration
• documentation_tools