Grouping function parameters with the help of sphinx

To group function parameters in Sphinx documentation in Persian, we must first familiarize ourselves with the concept of parameter grouping and the use of the standard documentation pattern in Sphinx. This tool is widely used for documenting programming projects, especially in the Python language. Stay with Radib until the end of this tutorial.

In Sphinx, we use the reStructuredText (rst.) format and plugins such as autodoc to automatically generate documentation from source code. One of the important features of this format is the detailed and structured explanation of parameters, return values, and function exceptions.

1. Basic Structure for Documenting Function Parameters in Sphinx

To document a function, you can use the following syntax in Sphinx:

def sample_function(param1: int, param2: str, param3: bool = True) -> str:
    """
    A brief description of the function.

    :param param1: Integer input
    :type param1: int
    :param param2: String input for the function
    :type param2: str
    :param param3: Default boolean value
    :type param3: bool
    :return: A string output
    :rtype: str
    """
    return f"{param1} - {param2} - {param3}"

In this example:

• :param is used to describe each parameter.
• :type specifies the parameter type.
• Explanations after these tags describe the role of each parameter.
• :return: explains the return value, while :rtype: specifies its type.

2. Grouping Parameters in Documentation

When dealing with functions that have a large number of parameters, it's better to group related parameters into categories. This can be done manually or using specific extensions.

Buy a virtual server with the best quality and price in Radib, click here

Manual Grouping Example:

def configure_server(ip_address: str, port: int, timeout: int, retry: bool, log_level: str):
    """
    Server configuration

    **Network Parameters:**
    :param ip_address: Server IP address
    :type ip_address: str
    :param port: Communication port
    :type port: int

    **Connection Settings:**
    :param timeout: Timeout duration in seconds
    :type timeout: int
    :param retry: Whether to retry requests or not
    :type retry: bool

    **Logging Parameters:**
    :param log_level: Logging level (DEBUG, INFO, ERROR)
    :type log_level: str
    """
    pass

In this example, text descriptions (**Section Title:**) are used to group parameters. This is a simple and effective approach.

3. Using sphinx.ext.napoleon Tags

The napoleon extension in Sphinx allows documentation in Google or NumPy style, providing better support for parameter grouping.

Example with Google Style:

def database_connection(host: str, port: int, username: str, password: str, use_ssl: bool) -> bool:
    """
    Connect to the database.

    Args:
        host (str): Database server address
        port (int): Connection port
        username (str): Username
        password (str): Password
        use_ssl (bool): Whether to establish a secure connection

    Returns:
        bool: Connection success status
    """
    return True

4. Enabling napoleon Extension

To enable this extension, open the conf.py file in Sphinx and add the following:

extensions = ['sphinx.ext.napoleon']

5. Automatically Generating Documentation with autodoc

If you want to automatically generate documentation from your code, you can run the following command:

sphinx-apidoc -o docs/ your_project/

Conclusion

By combining manual methods and the napoleon extension in Sphinx, you can create accurate, readable, and well-structured documentation for your functions and classes. If you are working on a large project, it is recommended to use the napoleon extension to facilitate the documentation process.