API Reference
=============

This page demonstrates how to document APIs using Sphinx.

Module Overview
---------------

.. module:: example_module
   :synopsis: Example module for demonstration purposes

This module provides examples of how to document Python APIs.

Classes
-------

.. class:: ExampleClass(name, value=None)

   A sample class for demonstration.

   :param str name: The name of the instance
   :param value: Optional initial value
   :type value: int or None
   
   .. attribute:: name
   
      The name of the instance (read-only)
      
      :type: str
   
   .. attribute:: value
   
      The current value
      
      :type: int
   
   .. method:: get_info()
   
      Get information about the instance.
      
      :returns: A dictionary containing name and value
      :rtype: dict
      
      Example:
      
      .. code-block:: python
      
         >>> obj = ExampleClass("test", 42)
         >>> obj.get_info()
         {'name': 'test', 'value': 42}
   
   .. method:: update_value(new_value)
   
      Update the instance value.
      
      :param int new_value: The new value to set
      :raises ValueError: If new_value is negative
      :returns: The previous value
      :rtype: int

Functions
---------

.. function:: calculate_sum(a, b)

   Calculate the sum of two numbers.

   :param float a: First number
   :param float b: Second number
   :returns: The sum of a and b
   :rtype: float
   
   Example:
   
   .. code-block:: python
   
      >>> calculate_sum(2.5, 3.7)
      6.2

.. function:: process_data(data, callback=None, **kwargs)

   Process data with optional callback.

   :param list data: List of items to process
   :param callable callback: Optional callback function
   :param kwargs: Additional keyword arguments
   :returns: Processed data
   :rtype: list
   :raises TypeError: If data is not a list

Constants
---------

.. data:: VERSION
   
   Current API version
   
   :type: str
   :value: "1.0.0"

.. data:: MAX_RETRIES
   
   Maximum number of retry attempts
   
   :type: int
   :value: 3

Exceptions
----------

.. exception:: CustomError

   Base exception for all custom errors.

.. exception:: ValidationError

   Raised when validation fails.
   
   .. attribute:: field
   
      The field that failed validation
      
   .. attribute:: message
   
      Error message

Code Examples
-------------

Basic Usage
^^^^^^^^^^^

.. code-block:: python

   from example_module import ExampleClass, calculate_sum
   
   # Create an instance
   obj = ExampleClass("demo", 100)
   
   # Use the calculate_sum function
   result = calculate_sum(10, 20)
   print(f"Sum: {result}")
   
   # Update value
   old_value = obj.update_value(200)
   print(f"Updated from {old_value} to {obj.value}")

Error Handling
^^^^^^^^^^^^^^

.. code-block:: python

   from example_module import ValidationError
   
   try:
       # Some validation code
       validate_input(user_data)
   except ValidationError as e:
       print(f"Validation failed for {e.field}: {e.message}")

See Also
--------

* :doc:`getting-started` - Introduction to the documentation
* :doc:`examples` - More comprehensive examples
* `Python Documentation <https://docs.python.org/3/>`_ - Official Python docs