Documentation Generator

osa_tool.osatreesitter.docgen.DocGen

Bases: object

This class is a utility for generating Python docstrings using OpenAI's GPT model. It includes methods for generating docstrings for a class, a single method, formatting the structure of Python files, counting the number of tokens in a given prompt, extracting the docstring from GPT's response, inserting a generated docstring into the source code and also processing a Python file by generating and inserting missing docstrings.

__init__(config_loader)

Instantiates the object of the class.

This method is a constructor that initializes the object by setting the 'api_key' attribute to the value of the 'OPENAI_API_KEY' environment variable.

context_extractor(method_details, structure)

Extracts the context of method calls and functions from given method_details and code structure.

Parameters:
- method_details: A dictionary containing details about the method calls.
- structure: A dictionary representing the code structure.

Returns:
A string containing the context of the method calls and functions in the format:
- If a method call is found:
  "# Method {method_name} in class {class_name}

{source_code}" - If a function call is found: "# Function {class_name} {source_code}"

Note:
- This method iterates over the method calls in method_details and searches for the corresponding methods and functions
  in the code structure. It constructs the context of the found methods and functions by appending their source code
  along with indicator comments.
- The returned string contains the structured context of all the detected methods and functions.

count_tokens(prompt)

Counts the number of tokens in a given prompt using a specified model.

Parameters:

Name	Type	Description	Default
prompt	str	The text for which to count the tokens.	required

Returns:

Type	Description
int	The number of tokens in the prompt.

create_mkdocs_github_workflow(repository_url, path, filename='osa_mkdocs', branches=None)

Generates GitHub workflow .yaml for MkDocs documentation for a Python project.

Parameters:

Name	Type	Description	Default
repository_url	str	str - URI of the Python project's repository on GitHub.	required
path	str	str - The path to the root directory of the Python project.	required
filename	str	str - The name of the .yaml file that contains GitHub workflow for mkdocs deploying.	'osa_mkdocs'
branches	list[str]	list[str] - List of branches to trigger the MkDocs workflow on	None

Returns:

Type	Description
None	None. The method generates GitHub workflow for MkDocs documentation of a current project.

extract_pure_docstring(gpt_response)

Extracts only the docstring from the GPT-4 response while keeping triple quotes.

Parameters:

Name	Type	Description	Default
gpt_response	str	The full response from GPT-4.	required

Returns:

Type	Description
str	The properly formatted docstring including triple quotes.

format_structure_openai(structure) staticmethod

Formats the structure of Python files in a readable string format.

This method iterates over the given dictionary 'structure' and generates a formatted string where it describes each file, its classes and functions along with their details such as line number, arguments, return type, source code and docstrings if available.

Parameters:

Name	Type	Description	Default
structure	dict	A dictionary containing details of the Python files structure. The dictionary should	required

Returns:

Type	Description
str	A formatted string representing the structure of the Python files.

format_with_black(filename)

Formats a Python source code file using the black code formatter.

This method takes a filename as input and formats the code in the specified file using the black code formatter.

Parameters:

Name	Type	Description	Default
-	filename	The path to the Python source code file to be formatted.	required

Returns:

Type	Description
	None

generate_class_documentation(class_details)

Generate documentation for a class.

Parameters:

Name	Type	Description	Default
class_details	dict	A list of dictionaries containing method names and their docstrings.	required

Returns:

Type	Description
str	The generated class docstring.

generate_documentation_mkdocs(path)

Generates MkDocs documentation for a Python project based on provided path.

Parameters:

Name	Type	Description	Default
path	str	str - The path to the root directory of the Python project.	required

Returns:

Type	Description
None	None. The method generates MkDocs documentation for the project.

generate_method_documentation(method_details, context_code=None)

Generate documentation for a single method.

insert_cls_docstring_in_code(source_code, class_name, generated_docstring)

Inserts a generated class docstring into the class definition.

Args:

source_code: The source code where the docstring should be inserted.
class_name: Class name.
generated_docstring: The docstring that should be inserted.

Returns:

Type	Description
str	The updated source code with the class docstring inserted.

insert_docstring_in_code(source_code, method_details, generated_docstring)

This method inserts a generated docstring into the specified location in the source code.

Parameters:

Name	Type	Description	Default
source_code	str	The source code where the docstring should be inserted.	required
method_details	dict	A dictionary containing details about the method. It should have a key 'method_name' with the name of the method where the docstring should be inserted.	required
generated_docstring	str	The docstring that should be inserted into the source code.	required

Returns:

Type	Description
str	None

process_python_file(parsed_structure)

Processes a Python file by generating and inserting missing docstrings.

This method iterates over the given parsed structure of a Python codebase, checks each class method for missing docstrings, and generates and inserts them if missing. The method updates the source file with the new docstrings and logs the path of the updated file.

Parameters:

Name	Type	Description	Default
parsed_structure	dict	A dictionary representing the parsed structure of the Python codebase. The dictionary keys are filenames and the values are lists of dictionaries representing classes and their methods.	required

Returns:

Type	Description
None	None