Was this page helpful?
Caution
You're viewing documentation for an unstable version of ScyllaDB Sphinx Theme. Switch to the latest stable version.
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'