Documentation Generator

class generate_documentation.GenerateDocumentation[source]

Bases: object

Generate documentation for a given file or function.

This class provides a way to generate documentation for a Python file or a specific function within the file. It extracts all the functions from the file, generates docstrings for each function, and saves the docstrings to a CSV file.

The generate_documentation method is the main entry point for this functionality. It performs the following steps:

  1. Extracts all the functions from the given file, or processes a specific function if provided.

  2. For each function, it generates a unique identifier based on the file path and function name.

  3. Checks if the function has already been processed by looking up the unique identifier in a CSV file.

  4. If the function has not been processed, it generates a call tree for the function using the CallTree class.

  5. Iterates through the functions in the call tree and generates docstrings for each function using the DocstringHandler class.

  6. Inserts the generated docstrings into the original file and saves the function details (file path, function name, unique identifier, and docstring) to a CSV file.

The class also provides helper methods to: - Extract all the functions from a given file. - Iterate through the functions in the call tree. - Process a function and generate its docstring. - Get the child context (docstrings of child functions) for a function.

Args:

file (str): The file path containing the functions to be documented. function_name (str, optional): The name of the specific function to be documented. If not provided, all functions in the file will be documented.

Raises:

FileNotFoundError: If the specified file is not found. SyntaxError: If there is a syntax error in the file.

Context from child functions (if any): {child_context}

extract_all_functions(file)[source]

Extract all function names from the given file.

This function reads the contents of the provided file, parses it using the ast module, and returns a list of all function and class names defined in the file.

The function uses the ast.parse() function to parse the contents of the file and create an abstract syntax tree (AST) representation of the code. It then iterates over the body of the AST and collects the names of all ast.FunctionDef and ast.ClassDef nodes, which represent function and class definitions, respectively.

Args:

file (str): The path to the file to be processed.

Returns:

list[str]: A list of all function and class names defined in the file.

generate_documentation(file, function_name=None)[source]

Generate documentation for a given file or a specific function.

This function extracts all the functions from the given file and generates docstrings for each function. If a specific function name is provided, it generates the docstring only for that function.

The function first extracts all the functions from the given file using the extract_all_functions method. It then iterates through each function and generates a unique ID for the function using the generate_unique_id function. If the function has already been processed, it fetches the docstring from a CSV file using the fetch_docstring_from_csv function.

If the function has not been processed, it generates a call tree for the function using the get_call_tree method of the CallTree class. It then iterates through the functions in the call tree and generates the docstrings using the iterate_through_functions and processing methods.

If any errors occur during the process, the function skips the function and continues with the next one.

Args:

file (str): The path to the file containing the functions. function_name (str, optional): The name of the specific function to generate the documentation for. If not provided, the function will generate documentation for all functions in the file.

Raises:

FileNotFoundError: If the file does not exist. SyntaxError: If there is a syntax error in the file.

get_child_context(function_name) → str[source]

Get the context of child functions for a given function name.

This function retrieves the context (function name and docstring) of the child functions associated with the provided function name. It iterates through the child functions, checks if they have been processed before, and retrieves their docstrings. The retrieved information is then concatenated and returned as a string.

Args:

function_name (str): The name of the function for which to retrieve the child context.

Returns:

str: The context of the child functions, including their names and docstrings, or an empty string if no child functions are found.

Raises:

KeyError: If the provided function name is not found in the function tree.

iterate_through_functions(function_name)[source]

Iterates through the functions in the function tree.

This function is responsible for iterating through the functions in the function tree. It takes a function name as input and checks if it exists in the tree. If the function exists, it iterates through the subfunctions associated with that function and calls the processing method for each subfunction.

Args:

function_name (str): The name of the function to iterate through.

Raises:

None

Returns:

None

processing(function_name)[source]

Process a function and generate its docstring.

This function is responsible for processing a given function and generating its docstring. It first checks if the function has already been processed and if so, retrieves the docstring from a CSV file. If the function has not been processed, it generates the docstring based on the function code and any child context.

The function first checks if the function is part of a class or not. If it is a class, it generates docstrings for all the methods in the class. If it is not a class, it iterates through the functions and generates the docstring for each one.

The function then generates the docstring using the DocstringHandler class and inserts it into the source code. It also saves the function details, including the unique ID, docstring, and function code, to a CSV file.

Args:

function_name (str): The name of the function to be processed.

Returns:

None