# Python

The [sphinx.ext.autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) extension generates documentation from Python docstrings.

## Basic usage

### Document a module

```rst
.. automodule:: examples._sample_module
   :members:
```

<a id="module-examples._sample_module"></a>

Sample module for demonstrating autodoc functionality.

This module provides a simple database connection class and utility functions
for demonstrating how API documentation is generated with sphinx.ext.autodoc.

### *class* DatabaseConnection(host, port=9042, username=None)

Manages connections to a database.

This class provides methods for connecting to, querying, and disconnecting
from a database. It’s designed to demonstrate autodoc’s ability to generate
documentation from Python docstrings.

* **Parameters:**
  * **host** (*str*) – The database host address
  * **port** (*int*) – The port number (default: 9042)
  * **username** (*str* *or* *None*) – Optional username for authentication

#### connect()

Establish a connection to the database.

* **Returns:**
  True if connection was successful
* **Return type:**
  bool
* **Raises:**
  **ConnectionError** – If connection fails

#### execute(query)

Execute a query on the database.

* **Parameters:**
  **query** (*str*) – The query string to execute
* **Returns:**
  Query results
* **Return type:**
  list
* **Raises:**
  **RuntimeError** – If not connected to database

#### disconnect()

Close the database connection.

### format_query(query, indent=4)

Format a database query for better readability.

This function takes a query string and formats it with proper indentation
and line breaks for improved readability in logs or documentation.

* **Parameters:**
  * **query** (*str*) – The query string to format
  * **indent** (*int*) – Number of spaces for indentation (default: 4)
* **Returns:**
  The formatted query string
* **Return type:**
  str

Example:

```pycon
>>> format_query("SELECT * FROM users")
'SELECT * FROM users'
```

### validate_connection_params(host, port)

Validate database connection parameters.

* **Parameters:**
  * **host** (*str*) – The database host address
  * **port** (*int*) – The port number
* **Returns:**
  True if parameters are valid, False otherwise
* **Return type:**
  bool

### DEFAULT_TIMEOUT *= 30*

Default connection timeout in seconds

### MAX_RETRIES *= 3*

Maximum number of connection retry attempts

### Document a class

```rst
.. autoclass:: examples._sample_module.DatabaseConnection
   :members:
```

### *class* DatabaseConnection(host, port=9042, username=None)

Manages connections to a database.

This class provides methods for connecting to, querying, and disconnecting
from a database. It’s designed to demonstrate autodoc’s ability to generate
documentation from Python docstrings.

* **Parameters:**
  * **host** (*str*) – The database host address
  * **port** (*int*) – The port number (default: 9042)
  * **username** (*str* *or* *None*) – Optional username for authentication

#### connect()

Establish a connection to the database.

* **Returns:**
  True if connection was successful
* **Return type:**
  bool
* **Raises:**
  **ConnectionError** – If connection fails

#### execute(query)

Execute a query on the database.

* **Parameters:**
  **query** (*str*) – The query string to execute
* **Returns:**
  Query results
* **Return type:**
  list
* **Raises:**
  **RuntimeError** – If not connected to database

#### disconnect()

Close the database connection.

### Document a function

```rst
.. autofunction:: examples._sample_module.format_query
```

### format_query(query, indent=4)

Format a database query for better readability.

This function takes a query string and formats it with proper indentation
and line breaks for improved readability in logs or documentation.

* **Parameters:**
  * **query** (*str*) – The query string to format
  * **indent** (*int*) – Number of spaces for indentation (default: 4)
* **Returns:**
  The formatted query string
* **Return type:**
  str

Example:

```pycon
>>> format_query("SELECT * FROM users")
'SELECT * FROM users'
```

## Common options

### Select specific members

```rst
.. autoclass:: examples._sample_module.DatabaseConnection
   :members: connect, disconnect
```

### Include special methods

```rst
.. autoclass:: examples._sample_module.DatabaseConnection
   :members:
   :special-members: __init__
```

### Include private members

```rst
.. autoclass:: examples._sample_module.DatabaseConnection
   :members:
   :private-members:
```

### Include undocumented members

```rst
.. automodule:: examples._sample_module
   :members:
   :undoc-members:
```

### Exclude members

```rst
.. autoclass:: examples._sample_module.DatabaseConnection
   :members:
   :exclude-members: disconnect
```

## Configuration

Set defaults in `conf.py`:

```python
autodoc_default_options = {
    'members': True,
    'member-order': 'bysource',
    'special-members': '__init__',
}

autodoc_typehints = 'signature'  # 'signature', 'description', 'none', 'both'
autodoc_member_order = 'bysource'  # 'alphabetical', 'bysource', 'groupwise'
```

## Related extensions

* `sphinx.ext.napoleon` - Google and NumPy docstring styles
* `sphinx.ext.autosummary` - Summary tables
* `sphinx.ext.viewcode` - Source code links