Contributing to Documentation
==========================

This guide explains how to write and maintain documentation for the Tessera project.
We use a combination of docstrings and RST files to provide comprehensive documentation.

Documentation Structure
--------------------
Our documentation consists of two main parts:

1. API Documentation (Docstrings):
   - Every module, class, method, and function must have a docstring
   - We use Google-style docstrings
   - Docstrings are processed by Sphinx's autodoc extension

2. Detailed Documentation (RST Files):
   - Located in the `docs/modules/` directory
   - Provides in-depth explanations, examples, and technical details
   - Organized to mirror the package structure

Writing Docstrings
---------------
Follow these guidelines for docstrings:

1. Module Docstrings::

    """
    :mod:`jam.module` --- Module Title
    ================================

    Brief description of the module.

    Core Components:
    * Component1: Description
    * Component2: Description

    Basic Usage::

        from jam.module import Component1

        # Example code
        result = Component1.do_something()
    """

2. Class Docstrings::

    class MyClass:
        """Class description.

        Detailed description of the class functionality.

        Args:
            param1: Description of first parameter
            param2: Description of second parameter

        Attributes:
            attr1: Description of first attribute
            attr2: Description of second attribute

        Examples:
            Basic usage::

                obj = MyClass(param1=1, param2="test")
                result = obj.method()
        """

3. Method/Function Docstrings::

    def my_function(param1: int, param2: str) -> bool:
        """Short description of function.

        Detailed description of what the function does.

        Args:
            param1: Description of first parameter
            param2: Description of second parameter

        Returns:
            Description of return value

        Raises:
            ErrorType: Description of when this error is raised

        Examples:
            Basic usage::

                result = my_function(1, "test")
                assert result is True
        """

Writing RST Documentation
----------------------
For each module, create or update these files:

1. Module Index (`index.rst`)::

    module_name package
    ==================

    Overview
    --------
    Technical description of the module.

    Core Components
    -------------
    * Component1: Description
    * Component2: Description

    Implementation Details
    -------------------
    Detailed technical information.

    Examples
    -------
    Code examples with explanations.

2. Component Documentation::

    component_name module
    ===================

    Technical Details
    --------------
    Implementation specifics.

    Usage Examples
    ------------
    Concrete examples with code.

    Error Handling
    ------------
    Error cases and their handling.

Adding New Documentation
---------------------
When adding a new module:

1. Write comprehensive docstrings in your code
2. Run the documentation generator::

    $ python docs/generate_docs.py

3. Create/edit the RST files in `docs/modules/your/module/`
4. Build and verify the documentation::

    $ cd docs
    $ sphinx-autobuild . _build/html

Documentation Standards
--------------------
1. Technical Focus:
   - Focus on implementation details
   - Provide concrete examples
   - Include error handling cases
   - Show exact byte-level formats where relevant

2. Code Examples:
   - All examples must be runnable
   - Include imports
   - Show expected outputs
   - Cover common use cases

3. Error Handling:
   - Document all possible errors
   - Explain when each error occurs
   - Show how to handle errors properly

4. Type Information:
   - Use type hints consistently
   - Document type constraints
   - Explain type conversions

Building Documentation
-------------------
To build the documentation locally:

1. Install dependencies::

    $ pip install sphinx sphinx-autobuild

2. Build the docs::

    $ cd docs
    $ sphinx-autobuild . _build/html

3. View at http://localhost:8000

Remember to:
- Keep docstrings focused and technical
- Provide detailed RST documentation
- Include runnable examples
- Document error cases
- Maintain type information