Was this page helpful?
Python¶
The sphinx.ext.autodoc extension generates documentation from Python docstrings.
Basic usage¶
Document a module¶
.. automodule:: examples._sample_module
:members:
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:
>>> 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¶
.. 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¶
.. 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:
>>> format_query("SELECT * FROM users") 'SELECT * FROM users'
Common options¶
Select specific members¶
.. autoclass:: examples._sample_module.DatabaseConnection
:members: connect, disconnect
Include special methods¶
.. autoclass:: examples._sample_module.DatabaseConnection
:members:
:special-members: __init__
Include private members¶
.. autoclass:: examples._sample_module.DatabaseConnection
:members:
:private-members:
Include undocumented members¶
.. automodule:: examples._sample_module
:members:
:undoc-members:
Exclude members¶
.. autoclass:: examples._sample_module.DatabaseConnection
:members:
:exclude-members: disconnect
Configuration¶
Set defaults in conf.py:
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'