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.
_format_class(item)
staticmethod
¶
Formats class details.
_format_class_doc(item)
¶
Formats documentation for a class.
_format_file_header(filename)
¶
Formats the header for a file in documentation.
_format_function(item)
staticmethod
¶
Formats function details.
_format_function_doc(item)
¶
Formats documentation for a standalone function.
_format_method(method)
staticmethod
¶
Formats method details.
_generate_method_doc(method_details, is_function=False)
¶
Generates documentation for a method or function.
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. |
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. |
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_openai(file_structure)
¶
Generates the documentation for a given file structure using OpenAI's API.
This method traverses the given file structure and for each class or standalone function, it generates its documentation. If the documentation is not available, it attempts to generate it using the OpenAI's API. The generated documentation is returned as a string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
self
|
The instance of the class where this method is defined. |
required | |
file_structure
|
dict
|
A dictionary where keys are filenames and values are lists of dictionaries. Each dictionary represents a class or a standalone function in the file and contains information like its name, type (class or function), docstring, and methods (in case of a class). |
required |
model
|
The model to be used by OpenAI's API to generate the documentation. Defaults to 'gpt-4'. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The final documentation as a string. |
generate_method_documentation(method_details)
¶
Generate documentation for a single method.
generate_method_documentation_md(method_details)
¶
Generate documentation for a single method using OpenAI GPT.
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 prints 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 |