Skip to content

Commit

Permalink
2.3: Finish generate_template.py (#15)
Browse files Browse the repository at this point in the history
* Finish generate_template.py

* add docs
mikem2m authored Jan 16, 2025

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
1 parent 783309c commit eae3c19
Showing 2 changed files with 78 additions and 30 deletions.
8 changes: 4 additions & 4 deletions src/fml_doc_gen/fml_doc_gen.py
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
from typing import Callable
from fml_doc_gen import FunctionDTO
from fml_doc_gen import write_docstring_to_file
from fml_doc_gen import read_user_function
from fml_doc_gen import generate_template
from func_dto import FunctionDTO
import write_docstring_to_file
import read_user_function
import generate_template

def generate_docstring_template(func: Callable, output_file: str, auto_generate: bool = False) -> str:
"""
100 changes: 74 additions & 26 deletions src/fml_doc_gen/generate_template.py
Original file line number Diff line number Diff line change
@@ -1,36 +1,84 @@
from typing import Callable
from fml_doc_gen import FunctionDTO
from func_dto import FunctionDTO

def generate_template(func_signature: FunctionDTO) -> str:
"""
Generates a docstring template with placeholders for parameters, return values, and a brief description
based on the provided function signature.
DOCSTRING_TEMPLATE = """
{function_name}:
### INSERT FUNCTION DEFINITION HERE ###
{function_parameters}
{function_output}
Examples:
--------
### INSERT FUNCTION EXAMPLE USAGES HERE ###
"""

Parameters
DOCSTRING_PARAMETERS_TEMPLATE = """
Parameters:
----------
func_signature : str
The signature of the user-defined function.
{function_params_str}
"""

DOCSTRING_PARAMETER_TEMPLATE = """
{param_name}: {param_type}
### INSERT PARAMETER DEFINITION HERE ###
"""

Returns
DOCSTRING_OUTPUT_TEMPLATE = """
Returns:
-------
str
The docstring template with placeholders.
{function_output_type}
### INSERT ADDITIONAL FUNCTION OUTPUT INFORMATION HERE ###
"""

Examples
--------
>>> func_signature = "example_func(a, b)"
>>> template = generate_template(func_signature)
>>> print(template)
\"\"\"Parameters
----------
a : type
b : type
DOCSTRING_PARAMETER_TYPE_PLACEHOLDER = "..."

Returns
-------
return_type
\"\"\"
def generate_template(function_signature: FunctionDTO) -> str:
"""
Generates a formatted docstring template for a function based on its name, inputs, and output type.
Args:
function_signature (FunctionDTO):
An object containing metadata about the function, including its name, input parameters,
and output type. The `inputs` attribute should be a list of tuples where each tuple contains
the name and type of a parameter.
Returns:
str: A string representing the generated docstring template for the function, formatted
with placeholders for detailed parameter and return value descriptions.
Raises:
ValueError: If the `name` attribute of the `function_signature` is empty.
Example:
>>> function_signature = FunctionDTO(
... name="add_numbers",
... output="int",
... inputs=[("a", "int"), ("b", "int")]
... )
>>> generate_template(function_signature)
"""
# Name logic
if not function_signature.name:
raise ValueError("The name of the function cannot be empty!")
function_name = function_signature.name

pass
# Parameters logic
function_params = []
for input_name, input_type in function_signature.inputs:
function_param = DOCSTRING_PARAMETER_TEMPLATE.format(
param_name = input_name,
param_type = input_type if input_type else DOCSTRING_PARAMETER_TYPE_PLACEHOLDER)
function_params.append(function_param)
function_params_str = "".join(function_params)
function_parameters = DOCSTRING_PARAMETERS_TEMPLATE.format(
function_params_str = function_params_str) if function_params_str else ""

# Output type
function_output_type = function_signature.output_type
function_output = DOCSTRING_OUTPUT_TEMPLATE.format(function_output_type = function_output_type) if function_output_type else ""

# Final template
return DOCSTRING_TEMPLATE.format(
function_name = function_name,
function_parameters = function_parameters,
function_output = function_output)

0 comments on commit eae3c19

Please sign in to comment.