diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 36c228e..203ccb9 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -22,4 +22,5 @@
- Add feature to get the signature representation of a Python function argument
- Add class for Python docstrings
- Add feature to parse Python docstrings
-- Add function to ensure a non-empty string.
\ No newline at end of file
+- Add function to ensure a non-empty string.
+- Add Python definition documentation generator
\ No newline at end of file
diff --git a/src/jcloud_docsgen/core/python/_core.py b/src/jcloud_docsgen/core/python/_core.py
index 209954a..497d364 100644
--- a/src/jcloud_docsgen/core/python/_core.py
+++ b/src/jcloud_docsgen/core/python/_core.py
@@ -13,15 +13,23 @@
# limitations under the License.
from __future__ import annotations
-from ...utils import ExistingDirectory, assert_that_is_instance, ExistingFile
+from ...utils import ExistingDirectory, assert_that_is_instance, ExistingFile, non_empty_str
+from ...exceptions import PythonArgumentStructureError
from .namespaces import PythonModuleNamespace, PythonPackageNamespace
-from .arguments import PythonASTArgumentsListParser
from .definitions import PythonDefinition, PythonFunctionDefinition, PythonAsyncFunctionDefinition, PythonClassDefinition
+from .arguments import PythonArgumentKind, PythonFunctionArgument
+from .docstrings import PythonDocstring
+from collections.abc import Iterator
+from typing import Union
+from dataclasses import dataclass
+from enum import Enum
+import docstring_parser
import pathlib
import ast
-from collections.abc import Iterator
__all__ = [
+ 'PythonDefinitionDocumentationIncludeSections',
+ 'PythonDefinitionDocumentationGenerator',
'PythonModuleDocumentationGenerator',
'PythonDocumentationGenerator',
]
@@ -44,6 +52,689 @@ def _collect_definitions(tree_or_node) -> Iterator[PythonDefinition]:
if isinstance(node, ast.ClassDef):
yield PythonClassDefinition.from_node(node)
+def _group_argument_list(argument_list: list[PythonFunctionArgument]) -> tuple[list[PythonFunctionArgument], list[PythonFunctionArgument], Union[PythonFunctionArgument, None], list[PythonFunctionArgument], Union[PythonFunctionArgument, None]]:
+ '''
+ Groups the argument list into a list of positional-only arguments, a
+ list of normal arguments, the * argument if there is one, a list of
+ keyword-only arguments and the var-keyword-argument if there is one.
+
+ :param argument_list: The argument list.
+ :type argument_list: list[PythonFunctionArgument]
+
+ :rtype: tuple[list[PythonFunctionArgument], list[PythonFunctionArgument], Union[PythonFunctionArgument, None], list[PythonFunctionArgument], Union[PythonFunctionArgument, None]]
+ '''
+
+ if argument_list:
+ if argument_list[-1].kind != PythonArgumentKind.KWARGS and any([
+ arg.kind == PythonArgumentKind.KWARGS
+ for arg in argument_list
+ ]):
+ raise PythonArgumentStructureError('arguments cannot follow var-keyword argument')
+
+ positional_only_args = []
+ normal_args = []
+ vararg = None
+ keyword_only_args = []
+ kwargs = None
+
+ for arg in argument_list:
+ if arg.kind == PythonArgumentKind.POSITIONAL_ONLY:
+ positional_only_args.append(arg)
+
+ if arg.kind == PythonArgumentKind.NORMAL:
+ normal_args.append(arg)
+
+ if arg.kind == PythonArgumentKind.VARARG:
+ if vararg is not None:
+ raise PythonArgumentStructureError('* argument may only appear once', definition = arg)
+ vararg = arg
+
+ if arg.kind == PythonArgumentKind.KEYWORD_ONLY:
+ keyword_only_args.append(arg)
+
+ if arg.kind == PythonArgumentKind.KWARGS:
+ kwargs = arg
+
+ return positional_only_args, normal_args, vararg, keyword_only_args, kwargs
+
+def _signature_argument_list(argument_list: list[PythonFunctionArgument]) -> list[str]:
+ '''
+ Returns a list of the arguments as strings for a function signature.
+
+ :param argument_list: The argument list.
+ :type argument_list: list[PythonFunctionArgument]
+
+ :return: The list of function signature argument strings.
+ :rtype: list[str]
+ '''
+
+ positional_only_args, normal_args, vararg, keyword_only_args, kwargs = _group_argument_list(argument_list)
+
+ args = []
+
+ for arg in positional_only_args:
+ args.append(arg.signature_repr())
+
+ if positional_only_args:
+ args.append('/')
+
+ for arg in normal_args:
+ args.append(arg.signature_repr())
+
+ if vararg is not None:
+ args.append(vararg.signature_repr())
+
+ if keyword_only_args and vararg is None:
+ args.append('*')
+
+ for arg in keyword_only_args:
+ args.append(arg.signature_repr())
+
+ if kwargs is not None:
+ args.append(kwargs.signature_repr())
+
+ return args
+
+def _fit_row_length(expected: int, row: tuple) -> tuple:
+ '''
+ Fits the row length to the expected length.
+
+ If the row is too long, the tail, that makes it too long, is omitted.
+ If it is too short, it is filled with ``None`` (at the end).
+
+ :param expected: The expected length.
+ :type expected: int
+ :param row: The row.
+ :type row: tuple
+ '''
+
+ if expected < 0:
+ raise ValueError('expected must be larger than or equal 0.')
+
+ if len(row) > expected:
+ return row[:expected]
+ else:
+ return row + (None,) * (expected - len(row))
+
+def _markdown_table(header: tuple, body: list[tuple], *, allow_markdown_table: bool = False, force_row_lengths: bool = False, one_line_values: bool = True, missing_value: str = '--') -> str:
+ '''
+ Generates a table.
+
+ If ``allow_markdown_table`` is ``False``, an alternative
+ representation is used.
+
+ :param headers: The table headers.
+ :type headers: tuple
+ :param body: The table body.
+ :type body: list[tuple]
+ :param allow_markdown_table: Controls whether a markdown table may be
+ used.
+ :type allow_markdown_table: bool
+ :param force_row_lengths: Controls whether an exception is raised if
+ a row does not have the correct length.
+ :type force_row_lengths: bool
+ :param one_line_values: Controls whether all newlines in all values
+ are replaced with spaces.
+ :type one_line_values: bool
+ :param missing_value: The string that is used if a value is missing
+ (only if ``force_row_lengths`` is ``False``).
+ :type missing_value: str
+ '''
+
+ if not header or not body:
+ return ''
+
+ header_len = len(header)
+
+ if allow_markdown_table:
+ table = '| ' + ' | '.join(header) + ' |\n|' + ' --- |' * len(header) + '\n'
+
+
+ for row in body:
+ if len(row) != header_len:
+ if force_row_lengths:
+ raise ValueError(f'expected {header_len} value{"s" if header_len > 1 else ""}, got {len(row)}')
+ else:
+ row = _fit_row_length(header_len, row)
+
+ table += '| ' + ' | '.join([
+ str(col if col is not None else missing_value).replace('\n', ' ')
+ if one_line_values
+ else str(col if col is not None else missing_value)
+ for col in row
+ ]) + ' |\n'
+ else:
+ table = ''
+
+ for row in body:
+ if len(row) != header_len:
+ if force_row_lengths:
+ raise ValueError(f'expected {header_len} value{"s" if header_len > 1 else ""}, got {len(row)}')
+ else:
+ row = _fit_row_length(header_len, row)
+
+ sep = '- '
+ for i, col in enumerate(row):
+ table += sep + header[i] + ': ' + (str(col if col is not None else missing_value).replace('\n', ' ') \
+ if one_line_values \
+ else str(col if col is not None else missing_value)) + '\n\n'
+ sep = ' '
+
+ return table.strip()
+
+def _is_docstring(docstring: Union[str, PythonDocstring, None]) -> bool:
+ '''
+ Checks whether the docstring is a docstring or an empty docstring.
+
+ :param docstring: The docstring.
+ :type docstring: Union[str, PythonDocstring, None]
+
+ :return: Whether there is a docstring.
+ :rtype: bool
+ '''
+
+ if docstring is None:
+ return False
+
+ if isinstance(docstring, PythonDocstring):
+ docstring = docstring.docstring
+
+ return docstring.strip() != ''
+
+@dataclass
+class _FunctionParamInfo:
+ annotation: Union[str, None]
+ description: Union[str, None]
+
+@dataclass
+class _NoDocstringTemplate:
+ description = None
+ params = []
+ raises = []
+ returns = None
+ many_returns = []
+ deprecation = None
+ examples = []
+ short_description = None
+ long_description = None
+ blank_after_short_description = None
+
+_NoDocstring = _NoDocstringTemplate()
+
+def _argument_kind_human_readable(argument_kind: PythonArgumentKind) -> str:
+ '''
+ Returns the human-readable representation of a
+ ``PythonArgumentKind``.
+
+ :param argument_kind: The argument kind.
+ :type argument_kind: PythonArgumentKind
+
+ :return: The human-readable representation.
+ :rtype: str
+ '''
+
+ return argument_kind.name.lower().replace('_', '-')
+
+def _function_params_info(arg_list: list[PythonFunctionArgument], docstring_arg_list: list[docstring_parser.DocstringParam]) -> dict[str, _FunctionParamInfo]:
+ '''
+ Returns a dictionary with the parameter info.
+
+ The keys of the dictionary are the parameter names and the values are
+ their types. If there is no type annotation for a parameter, the type
+ in the docstring is used as a fallback. If the docstring also does
+ not contain the type for a parameter, its value in the dictionary is
+ set to ``None``.
+
+ :param arg_list: The list of parameters from the function parameter
+ list.
+ :type arg_list: list[PythonFunctionArgument]
+ :param docstring_arg_list: The list of parameters from the docstring
+ parameter list.
+
+ :return: The dictionary with the parameter types.
+ :rtype: dict[str, _FunctionParamInfo]
+ '''
+
+ arg_annotations = {arg.name: _FunctionParamInfo(arg.annotation, None) for arg in arg_list}
+
+ for arg in docstring_arg_list:
+ if arg.arg_name in arg_annotations.keys():
+ arg_annotations[arg.arg_name] = _FunctionParamInfo(
+ arg_annotations[arg.arg_name].annotation or arg.type_name,
+ arg.description
+ )
+
+ return arg_annotations
+
+class PythonDefinitionDocumentationIncludeSections:
+ '''
+ A class representing the included sections in a Python definition
+ documentation.
+
+ :param signature: Whether include the signature section.
+ :type signature: bool
+ :param returns: Whether include the returns section.
+ :type returns: bool
+ :param params: Whether include the params section.
+ :type params: bool
+ :param exceptions: Whether include the exceptions section.
+ :type exceptions: bool
+ :param examples: Whether include the examples section.
+ :type examples: bool
+ :param docstring: Whether include the docstring section.
+ :type docstring: bool
+ :param bases: Whether include the bases section.
+ :type bases: bool
+ :param decorators: Whether include the decorators section.
+ :type decorators: bool
+ '''
+
+ def __init__(
+ self,
+ *,
+ signature: bool = True,
+ returns: bool = True,
+ params: bool = True,
+ exceptions: bool = True,
+ examples: bool = True,
+ docstring: bool = True,
+ bases: bool = True,
+ decorators: bool = True,
+ class_body: bool = True
+ ):
+ self.signature = signature
+ self.returns = returns
+ self.params = params
+ self.exceptions = exceptions
+ self.examples = examples
+ self.docstring = docstring
+ self.bases = bases
+ self.decorators = decorators
+ self.class_body = class_body
+
+ self._args = {
+ 'signature': self.signature,
+ 'returns': self.returns,
+ 'params': self.params,
+ 'exceptions': self.exceptions,
+ 'examples': self.examples,
+ 'docstring': self.docstring,
+ 'bases': self.bases,
+ 'decorators': self.decorators,
+ 'class_body': self.class_body,
+ }
+
+ def __repr__(self) -> str:
+ return type(self).__name__+ '(' + ', '.join(
+ [
+ key + ' = ' + repr(value)
+ for key, value in self._args.items()
+ ]
+ ) + ')'
+
+ def __eq__(self, value) -> str:
+ if not isinstance(value, PythonDefinitionDocumentationIncludeSections):
+ return False
+ return self._args == value._args
+
+class PythonDefinitionDocumentationGenerator:
+ '''
+ A documentation generator for a Python definition.
+
+ :param definition: The Python definition.
+ :type definition: PythonDefinition
+ :param include_sections: The sections that will be included.
+ :type include_sections: PythonDefinitionDocumentationIncludeSections
+ :param level: The level of the definition in the markdown content.
+ :type level: int
+ :param allow_html: Controls whether the generated documentation may
+ contain HTML.
+ :type allow_html: bool
+ :param allow_tables: Controls whether the generated documentation may
+ contain tables.
+ :type allow_tables: bool
+ :param skip_empty_sections: Controls whether sections that does not
+ have any content (such as the parameters
+ section if there are no parameters taken)
+ are skipped. If ``False``, a short text
+ (such as 'This function takes no
+ parameters') is used.
+ :type skip_empty_sections: bool
+ :param is_method: Controls whether the definition is a class method.
+ :type is_method: bool
+ '''
+
+ def __init__(
+ self,
+ definition: PythonDefinition,
+ include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(),
+ *,
+ level: int = 1,
+ allow_html: bool = True,
+ allow_tables: bool = False,
+ skip_empty_sections: bool = True,
+ is_method: bool = False
+ ) -> None:
+ self.definition = definition
+ self.include_sections = include_sections
+
+ self.level = level
+ self.allow_html = allow_html
+ self.allow_tables = allow_tables
+ self.skip_empty_sections = skip_empty_sections
+ self.is_method = is_method
+
+ self._docstring_cache = None
+
+ @property
+ def _docstring(self):
+ if self._docstring_cache is None:
+ self._docstring_cache = self.definition.doc.parse() if _is_docstring(self.definition.doc) else _NoDocstring
+ return self._docstring_cache
+
+ def generate_signature(self) -> str:
+ '''
+ Generates the signature of the definition. Works only if the
+ definition is a function or asynchronous function definition.
+
+ :raises TypeError: If the definition is a class definition.
+
+ :return: The signature.
+ :rtype: str
+ '''
+
+ if isinstance(self.definition, PythonClassDefinition):
+ raise TypeError('Cannot generate a signature of a class definition.')
+
+ signature = self.definition.name + '(' + ', '.join(_signature_argument_list(self.definition.args)) + ')'
+
+ if self.definition.returns is not None:
+ signature += ' -> ' + self.definition.returns
+
+ return signature.strip()
+
+ def _generate_signature_section(self) -> str:
+ '''
+ Generates the signature section.
+
+ :return: The signature section.
+ :rtype: str
+ '''
+
+ return self.level * '#' + '# ' + ('Function' if not self.is_method else 'Method') +' signature\n\n```python\n' + self.generate_signature() + '\n```'
+
+ def _generate_docstring_section(self) -> str:
+ '''
+ Generates the docstring section.
+
+ :return: The docstring section.
+ :rtype: str
+ '''
+
+ md = ''
+
+ if _is_docstring(self.definition.doc) or not self.skip_empty_sections:
+ if self.allow_html:
+ md += 'Docstring' + '
'
+ else:
+ md += self.level * '#' + '# Docstring\n\n'
+
+ if _is_docstring(self.definition.doc):
+ md += self.definition.doc.docstring
+ elif not self.skip_empty_sections:
+ md += 'There is no docstring to show.'
+
+ if _is_docstring(self.definition.doc) or not self.skip_empty_sections:
+ if self.allow_html:
+ md += 'Docstring
aDocstring
a\nbDocstring
There is no docstring to show.Docstring
There is no docstring to show.Docstring
aDocstring
a\nbDocstring
A function.
+
+Very long ...
+
+:param hello: A parameter.
+:type hello: str
+:param something: Something.
+:param value: The value.
+:type value: object
+
+:raises ValueError: If the value is invalid.
+
+:return: The return value.
+:rtype: listDocstring
A function.
+
+Very long ...
+
+:param hello: A parameter.
+:type hello: str
+:param something: Something.
+:param value: The value.
+:type value: object
+
+:raises ValueError: If the value is invalid.
+
+:return: The return value.
+:rtype: listDocstring
A function.
+
+Very long ...
+
+:param hello: A parameter.
+:type hello: str
+:param something: Something.
+:param value: The value.
+:type value: object
+
+:raises ValueError: If the value is invalid.
+
+:return: The return value.
+:rtype: listDocstring
A function.
+
+Very long ...
+
+:param hello: A parameter.
+:type hello: str
+:param something: Something.
+:param value: The value.
+:type value: object
+
+:raises ValueError: If the value is invalid.
+
+:return: The return value.
+:rtype: list