From 81b2be7efc966c1e0057d5db22511226d5493e98 Mon Sep 17 00:00:00 2001 From: Jakob Scheid Date: Mon, 27 Apr 2026 22:43:26 +0200 Subject: [PATCH] Add API reference --- .../jcloud_docsgen/core/python/_core.md | 1318 +++++++++++++++++ .../jcloud_docsgen/core/python/arguments.md | 205 +++ .../jcloud_docsgen/core/python/definitions.md | 445 ++++++ .../jcloud_docsgen/core/python/docstrings.md | 113 ++ .../jcloud_docsgen/core/python/namespaces.md | 442 ++++++ docs/reference/jcloud_docsgen/exceptions.md | 253 ++++ docs/reference/jcloud_docsgen/utils.md | 335 +++++ 7 files changed, 3111 insertions(+) create mode 100644 docs/reference/jcloud_docsgen/core/python/_core.md create mode 100644 docs/reference/jcloud_docsgen/core/python/arguments.md create mode 100644 docs/reference/jcloud_docsgen/core/python/definitions.md create mode 100644 docs/reference/jcloud_docsgen/core/python/docstrings.md create mode 100644 docs/reference/jcloud_docsgen/core/python/namespaces.md create mode 100644 docs/reference/jcloud_docsgen/exceptions.md create mode 100644 docs/reference/jcloud_docsgen/utils.md diff --git a/docs/reference/jcloud_docsgen/core/python/_core.md b/docs/reference/jcloud_docsgen/core/python/_core.md new file mode 100644 index 0000000..7286ece --- /dev/null +++ b/docs/reference/jcloud_docsgen/core/python/_core.md @@ -0,0 +1,1318 @@ +# Module `jcloud_docsgen.core.python._core` + +## Function `_collect_definitions` + +Collects all definitions of the tree or node. + + +### Function signature + +```python +_collect_definitions(tree_or_node) -> Iterator[PythonDefinition] +``` + +### Returns + +The definitions. + +Return type: `Iterator[PythonDefinition]` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `tree_or_node` | -- | normal | -- | The tree or node. | + + + + + + + +### Docstring + +Collects all definitions of the tree or node. + +:param tree_or_node: The tree or node. + +:return: The definitions. +:rtype: Iterator[PythonDefinition] + +## Function `_group_argument_list` + +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. + +### Function signature + +```python +_group_argument_list(argument_list: list[PythonFunctionArgument]) -> tuple[list[PythonFunctionArgument], list[PythonFunctionArgument], Union[PythonFunctionArgument, None], list[PythonFunctionArgument], Union[PythonFunctionArgument, None]] +``` + +### Returns + +Return type: `tuple[list[PythonFunctionArgument], list[PythonFunctionArgument], Union[PythonFunctionArgument, None], list[PythonFunctionArgument], Union[PythonFunctionArgument, None]]` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `argument_list` | `list[PythonFunctionArgument]` | normal | -- | The argument list. | + + + + + + + +### Docstring + +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]] + +## Function `_signature_argument_list` + +Returns a list of the arguments as strings for a function signature. + + +### Function signature + +```python +_signature_argument_list(argument_list: list[PythonFunctionArgument]) -> list[str] +``` + +### Returns + +The list of function signature argument strings. + +Return type: `list[str]` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `argument_list` | `list[PythonFunctionArgument]` | normal | -- | The argument list. | + + + + + + + +### Docstring + +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] + +## Function `_fit_row_length` + +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). + +### Function signature + +```python +_fit_row_length(expected: int, row: tuple) -> tuple +``` + +### Returns + +Return type: `tuple` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `expected` | `int` | normal | -- | The expected length. | +| `row` | `tuple` | normal | -- | The row. | + + + + + + + +### Docstring + +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 + +## Function `_markdown_table` + +Generates a table. + +If ``allow_markdown_table`` is ``False``, an alternative +representation is used. + +### Function signature + +```python +_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 +``` + +### Returns + +Return type: `str` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `header` | `tuple` | normal | -- | -- | +| `body` | `list[tuple]` | normal | -- | The table body. | +| `allow_markdown_table` | `bool` | keyword-only | `False` | Controls whether a markdown table may be used. | +| `force_row_lengths` | `bool` | keyword-only | `False` | Controls whether an exception is raised if a row does not have the correct length. | +| `one_line_values` | `bool` | keyword-only | `True` | Controls whether all newlines in all values are replaced with spaces. | +| `missing_value` | `str` | keyword-only | `'--'` | The string that is used if a value is missing (only if ``force_row_lengths`` is ``False``). | + + + + + + + +### Docstring + +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 + +## Function `_is_docstring` + +Checks whether the docstring is a docstring or an empty docstring. + + +### Function signature + +```python +_is_docstring(docstring: Union[str, PythonDocstring, None]) -> bool +``` + +### Returns + +Whether there is a docstring. + +Return type: `bool` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `docstring` | `Union[str, PythonDocstring, None]` | normal | -- | The docstring. | + + + + + + + +### Docstring + +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 + +## Class `_FunctionParamInfo` + + + + + +### Decorators + +```python +dataclass +``` + +## Class `_NoDocstringTemplate` + + + + + +### Decorators + +```python +dataclass +``` + +## Function `_argument_kind_human_readable` + +Returns the human-readable representation of a +``PythonArgumentKind``. + +### Function signature + +```python +_argument_kind_human_readable(argument_kind: PythonArgumentKind) -> str +``` + +### Returns + +The human-readable representation. + +Return type: `str` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `argument_kind` | `PythonArgumentKind` | normal | -- | The argument kind. | + + + + + + + +### Docstring + +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 + +## Function `_function_params_info` + +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``. + +### Function signature + +```python +_function_params_info(arg_list: list[PythonFunctionArgument], docstring_arg_list: list[docstring_parser.DocstringParam]) -> dict[str, _FunctionParamInfo] +``` + +### Returns + +The dictionary with the parameter types. + +Return type: `dict[str, _FunctionParamInfo]` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `arg_list` | `list[PythonFunctionArgument]` | normal | -- | The list of parameters from the function parameter list. | +| `docstring_arg_list` | `list[docstring_parser.DocstringParam]` | normal | -- | The list of parameters from the docstring parameter list. | + + + + + + + +### Docstring + +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] + +## Class `PythonDefinitionDocumentationIncludeSections` + +A class representing the included sections in a Python definition +documentation. + + + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__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) +``` + + + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `signature` | `bool` | keyword-only | `True` | -- | +| `returns` | `bool` | keyword-only | `True` | -- | +| `params` | `bool` | keyword-only | `True` | -- | +| `exceptions` | `bool` | keyword-only | `True` | -- | +| `examples` | `bool` | keyword-only | `True` | -- | +| `docstring` | `bool` | keyword-only | `True` | -- | +| `bases` | `bool` | keyword-only | `True` | -- | +| `decorators` | `bool` | keyword-only | `True` | -- | +| `class_body` | `bool` | keyword-only | `True` | -- | + +#### Method `__repr__` + +##### Method signature + +```python +__repr__(self) -> str +``` + +##### Returns + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + +#### Method `__eq__` + +##### Method signature + +```python +__eq__(self, value) -> str +``` + +##### Returns + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `value` | -- | normal | -- | -- | + + + + + +### Docstring + +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 + +## Class `PythonDefinitionDocumentationGenerator` + +A documentation generator for a Python definition. + + + + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__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 +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `definition` | `PythonDefinition` | normal | -- | -- | +| `include_sections` | `PythonDefinitionDocumentationIncludeSections` | normal | `PythonDefinitionDocumentationIncludeSections()` | -- | +| `level` | `int` | normal | `1` | -- | +| `allow_html` | `bool` | keyword-only | `True` | -- | +| `allow_tables` | `bool` | keyword-only | `False` | -- | +| `skip_empty_sections` | `bool` | keyword-only | `True` | -- | +| `is_method` | `bool` | keyword-only | `False` | -- | + +#### Method `_docstring` + +##### Method signature + +```python +_docstring(self) +``` + + + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + +##### Decorators + +```python +property +``` + +#### Method `generate_signature` + +Generates the signature of the definition. Works only if the +definition is a function or asynchronous function definition. + +##### Method signature + +```python +generate_signature(self) -> str +``` + +##### Returns + +The signature. + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + +##### Exceptions + +| Exception | Description | +| --- | --- | +| `TypeError` | If the definition is a class definition. | + + + + + +##### Docstring + +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 + +#### Method `_generate_signature_section` + +Generates the signature section. + + +##### Method signature + +```python +_generate_signature_section(self) -> str +``` + +##### Returns + +The signature section. + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Generates the signature section. + +:return: The signature section. +:rtype: str + +#### Method `_generate_docstring_section` + +Generates the docstring section. + + +##### Method signature + +```python +_generate_docstring_section(self) -> str +``` + +##### Returns + +The docstring section. + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Generates the docstring section. + +:return: The docstring section. +:rtype: str + +#### Method `_generate_params_section` + +Generates the parameters section. + + +##### Method signature + +```python +_generate_params_section(self) -> str +``` + +##### Returns + +The parameters section. + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Generates the parameters section. + +:return: The parameters section. +:rtype: str + +#### Method `_generate_returns_section` + +Generates the returns section. + + +##### Method signature + +```python +_generate_returns_section(self) -> str +``` + +##### Returns + +The returns section. + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Generates the returns section. + +:return: The returns section. +:rtype: str + +#### Method `_generate_exceptions_section` + +Generates the exceptions section. + + +##### Method signature + +```python +_generate_exceptions_section(self) -> str +``` + +##### Returns + +The exceptions section. + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Generates the exceptions section. + +:return: The exceptions section. +:rtype: str + +#### Method `_generate_examples_section` + +Generates the examples section. + + +##### Method signature + +```python +_generate_examples_section(self) -> str +``` + +##### Returns + +The examples section. + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Generates the examples section. + +:return: The examples section. +:rtype: str + +#### Method `_generate_decorators_section` + +Generates the decorators section. + + +##### Method signature + +```python +_generate_decorators_section(self) -> str +``` + +##### Returns + +The decorators section. + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Generates the decorators section. + +:return: The decorators section. +:rtype: str + +#### Method `_generate_bases_section` + +Generates the bases section. + + +##### Method signature + +```python +_generate_bases_section(self) -> str +``` + +##### Returns + +The bases section. + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Generates the bases section. + +:return: The bases section. +:rtype: str + +#### Method `_generate_body_section` + +Generates the body section. + + +##### Method signature + +```python +_generate_body_section(self) -> str +``` + +##### Returns + +The body section. + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Generates the body section. + +:return: The body section. +:rtype: str + +#### Method `generate_documentation` + +Generates the documentation in the markdown format. + + +##### Method signature + +```python +generate_documentation(self) -> str +``` + +##### Returns + +The documentation. + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Generates the documentation in the markdown format. + +:return: The documentation. +:rtype: str + + + + + +### Docstring + +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 + +## Class `PythonModuleDocumentationGenerator` + +A documentation generator for a Python module. + + + + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, module_path: ExistingFile, src_directory: Union[ExistingDirectory, None] = None, include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(), **kwargs) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `module_path` | `ExistingFile` | normal | -- | -- | +| `src_directory` | `Union[ExistingDirectory, None]` | normal | `None` | -- | +| `include_sections` | `PythonDefinitionDocumentationIncludeSections` | normal | `PythonDefinitionDocumentationIncludeSections()` | -- | +| `kwargs` | -- | kwargs | -- | -- | + +#### Method `_source_code` + +##### Method signature + +```python +_source_code(self) -> str +``` + +##### Returns + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + +##### Decorators + +```python +property +``` + +#### Method `_ast` + +##### Method signature + +```python +_ast(self) -> str +``` + +##### Returns + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + +##### Decorators + +```python +property +``` + +#### Method `collect_definitions` + +Collects all function and class definitions of the module. + + +##### Method signature + +```python +collect_definitions(self) -> Iterator[PythonDefinition] +``` + +##### Returns + +All definitions of the module + +Return type: `Iterator[PythonDefinition]` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Collects all function and class definitions of the module. + +:return: All definitions of the module +:rtype: Iterator[PythonDefinition] + +#### Method `generate_documentation` + +Generates the documentation in the markdown format. + + +##### Method signature + +```python +generate_documentation(self) -> str +``` + +##### Returns + +The documentation. + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Generates the documentation in the markdown format. + +:return: The documentation. +:rtype: str + + + + + +### Docstring + +A documentation generator for a Python module. + +:param module_path: The path of the module file. +:type module_path: ExistingFile +:param src_directory: The directory of the source code. It is + optional and only used for making the module + identifiers in the documentation relative. +:type src_directory: Union[ExistingDirectory, None] +:param include_sections: The sections that will be included. +:type include_sections: PythonDefinitionDocumentationIncludeSections +:param kwargs: The options for ``PythonDefinitionDocumentationGenerator``. + +## Function `_generate_package_namespace_documentation` + +Generates the documentation for a package namespace and writes it to +the documentation directory. + +### Function signature + +```python +_generate_package_namespace_documentation(namespace: PythonPackageNamespace, documentation_directory: pathlib.Path, root_directory: pathlib.Path, dir: pathlib.Path, include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(), kwargs: dict = {}) -> None +``` + +### Returns + +Return type: `None` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `namespace` | `PythonPackageNamespace` | normal | -- | The namespace. | +| `documentation_directory` | `pathlib.Path` | normal | -- | The directory for the documentation. | +| `root_directory` | `pathlib.Path` | normal | -- | The root directory. | +| `dir` | `pathlib.Path` | normal | -- | The directory of the namespace. | +| `include_sections` | `PythonDefinitionDocumentationIncludeSections` | normal | `PythonDefinitionDocumentationIncludeSections()` | The sections to be included in the documentation. | +| `kwargs` | `dict` | normal | `{}` | The options for the documentation generator. | + + + + + + + +### Docstring + +Generates the documentation for a package namespace and writes it to +the documentation directory. + +:param namespace: The namespace. +:type namespace: PythonPackageNamespace +:param documentation_directory: The directory for the documentation. +:type documentation_directory: pathlib.Path +:param root_directory: The root directory. +:type root_directory: pathlib.Path +:param dir: The directory of the namespace. +:type dir: pathlib.Path +:param include_sections: The sections to be included in the documentation. +:type include_sections: PythonDefinitionDocumentationIncludeSections +:param kwargs: The options for the documentation generator. + +## Class `PythonDocumentationGenerator` + +The class for the documentation generator. + + + + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, project_directory: ExistingDirectory, docs_directory: ExistingDirectory, include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(), **kwargs) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `project_directory` | `ExistingDirectory` | normal | -- | -- | +| `docs_directory` | `ExistingDirectory` | normal | -- | -- | +| `include_sections` | `PythonDefinitionDocumentationIncludeSections` | normal | `PythonDefinitionDocumentationIncludeSections()` | -- | +| `kwargs` | -- | kwargs | -- | -- | + +#### Method `_namespace` + +##### Method signature + +```python +_namespace(self, directory: pathlib.Path) -> PythonPackageNamespace +``` + +##### Returns + +Return type: `PythonPackageNamespace` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `directory` | `pathlib.Path` | normal | -- | -- | + +#### Method `namespace` + +Returns the project as a namespace. + + +##### Method signature + +```python +namespace(self) -> list[PythonPackageNamespace] +``` + +##### Returns + +The project as a namespace. + +Return type: `list[PythonPackageNamespace]` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Returns the project as a namespace. + +:return: The project as a namespace. +:rtype: list[PythonPackageNamespace] + +#### Method `generate_documentation` + +Generates the full project documentation and writes it to the +documentation directory. + +##### Method signature + +```python +generate_documentation(self) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Generates the full project documentation and writes it to the +documentation directory. + + + + + +### Docstring + +The class for the documentation generator. + +:param project_directory: The directory of the project. +:type project_directory: ExistingDirectory +:param docs_directory: The directory for the generated documentation. +:type docs_directory: ExistingDirectory +:param include_sections: The sections to be included in the documentation. +:type include_sections: PythonDefinitionDocumentationIncludeSections +:param kwargs: The options for ``PythonDefinitionDocumentationGenerator``. \ No newline at end of file diff --git a/docs/reference/jcloud_docsgen/core/python/arguments.md b/docs/reference/jcloud_docsgen/core/python/arguments.md new file mode 100644 index 0000000..683fc3c --- /dev/null +++ b/docs/reference/jcloud_docsgen/core/python/arguments.md @@ -0,0 +1,205 @@ +# Module `jcloud_docsgen.core.python.arguments` + +## Class `PythonArgumentKind` + +### Base classes + +- `Enum` + +## Class `PythonFunctionArgument` + +Represents an argument of a Python function. + + + + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, name: str, kind: PythonArgumentKind, default: Union[str, None], annotation: Union[str, None]) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `name` | `str` | normal | -- | -- | +| `kind` | `PythonArgumentKind` | normal | -- | -- | +| `default` | `Union[str, None]` | normal | -- | -- | +| `annotation` | `Union[str, None]` | normal | -- | -- | + +#### Method `__eq__` + +##### Method signature + +```python +__eq__(self, value: PythonFunctionArgument) -> bool +``` + +##### Returns + +Return type: `bool` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `value` | `PythonFunctionArgument` | normal | -- | -- | + +#### Method `__repr__` + +##### Method signature + +```python +__repr__(self) -> str +``` + +##### Returns + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + +#### Method `signature_repr` + +Returns the function signature representation of the argument. + + +##### Method signature + +```python +signature_repr(self) -> str +``` + +##### Returns + +The string representation of the argument. + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Returns the function signature representation of the argument. + +:return: The string representation of the argument. +:rtype: str + + + + + +### Docstring + +Represents an argument of a Python function. + +:param name: The name of the argument. +:type name: str +:param kind: The kind of the argument. +:type kind: ArgumentKind +:param default: The default value of the argument. +:type default: Union[str, None] +:param annotation: The type annotation of the argument. +:type annotation: Union[str, None] + +## Class `PythonASTArgumentsListParser` + +A parser for making ``PythonFunctionArgument`` objects from an +``ast.arguments`` arguments list. + + + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, ast_arguments_list: ast.arguments) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `ast_arguments_list` | `ast.arguments` | normal | -- | -- | + +#### Method `to_argument_list` + +Converts the AST arguments list to a list of Python function +argument objects. + +##### Method signature + +```python +to_argument_list(self) -> list[PythonFunctionArgument] +``` + +##### Returns + +The list of Python function argument objects. + +Return type: `list[PythonFunctionArgument]` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Converts the AST arguments list to a list of Python function +argument objects. + +:return: The list of Python function argument objects. +:rtype: list[PythonFunctionArgument] + + + + + +### Docstring + +A parser for making ``PythonFunctionArgument`` objects from an +``ast.arguments`` arguments list. + +:param ast_arguments_list: The ``ast.arguments`` arguments list. +:type ast_arguments_list: ast.arguments \ No newline at end of file diff --git a/docs/reference/jcloud_docsgen/core/python/definitions.md b/docs/reference/jcloud_docsgen/core/python/definitions.md new file mode 100644 index 0000000..14e1d1a --- /dev/null +++ b/docs/reference/jcloud_docsgen/core/python/definitions.md @@ -0,0 +1,445 @@ +# Module `jcloud_docsgen.core.python.definitions` + +## Function `_python_docstring` + +Returns the PythonDocstring object if the docstring is a string and +not ``None``. + +### Function signature + +```python +_python_docstring(doc: Union[str, None]) -> Union[PythonDocstring, None] +``` + +### Returns + +The PythonDocstring object or ``None``. + +Return type: `Union[PythonDocstring, None]` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `doc` | `Union[str, None]` | normal | -- | The docstring. | + + + + + + + +### Docstring + +Returns the PythonDocstring object if the docstring is a string and +not ``None``. + +:param doc: The docstring. +:type doc: Union[str, None] + +:return: The PythonDocstring object or ``None``. +:rtype: Union[PythonDocstring, None] + +## Class `PythonDefinition` + +A base class for Python definition (a class, function or asynchronous +function definition) classes. + + + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, name: str, doc: Union[PythonDocstring, None], decorators: list[str]) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `name` | `str` | normal | -- | -- | +| `doc` | `Union[PythonDocstring, None]` | normal | -- | -- | +| `decorators` | `list[str]` | normal | -- | -- | + +#### Method `_arg_list` + +##### Method signature + +```python +_arg_list(self) -> tuple +``` + +##### Returns + +Return type: `tuple` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + +#### Method `__repr__` + +##### Method signature + +```python +__repr__(self) -> str +``` + +##### Returns + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + +#### Method `from_node` + +From an AST node. + + +##### Method signature + +```python +from_node(cls, node: ast.stmt) -> PythonDefinition +``` + +##### Returns + +Return type: `PythonDefinition` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `cls` | -- | normal | -- | -- | +| `node` | `ast.stmt` | normal | -- | The AST node. | + + + +##### Decorators + +```python +classmethod +``` + + + +##### Docstring + +From an AST node. + +:param node: The AST node. +:type node: ast.stmt + +#### Method `__eq__` + +##### Method signature + +```python +__eq__(self, value: object) -> bool +``` + +##### Returns + +Return type: `bool` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `value` | `object` | normal | -- | -- | + + + + + +### Docstring + +A base class for Python definition (a class, function or asynchronous +function definition) classes. + +:param name: The name of the definition. +:type name: str +:param doc: The docstring. +:type doc: Union[PythonDocstring, None] +:param decorators: The definition decorators. +:type decorators: list[str] + +:raises InvalidPythonIdentifierError: If the name is not a valid + Python identifier. + +## Class `PythonFunctionDefinition` + +A PythonDefinition subclass representing a Python function +definition. + +### Base classes + +- `PythonDefinition` + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, name: str, args: list[PythonFunctionArgument], returns: Union[str, None], doc: Union[PythonDocstring, None], decorators: list[str]) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `name` | `str` | normal | -- | -- | +| `args` | `list[PythonFunctionArgument]` | normal | -- | -- | +| `returns` | `Union[str, None]` | normal | -- | -- | +| `doc` | `Union[PythonDocstring, None]` | normal | -- | -- | +| `decorators` | `list[str]` | normal | -- | -- | + +#### Method `_arg_list` + +##### Method signature + +```python +_arg_list(self) -> tuple +``` + +##### Returns + +Return type: `tuple` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + +#### Method `from_node` + +From an AST node. + + +##### Method signature + +```python +from_node(cls, node: ast.stmt) -> PythonFunctionDefinition +``` + +##### Returns + +Return type: `PythonFunctionDefinition` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `cls` | -- | normal | -- | -- | +| `node` | `ast.stmt` | normal | -- | The AST node. | + + + +##### Decorators + +```python +classmethod +``` + + + +##### Docstring + +From an AST node. + +:param node: The AST node. +:type node: ast.stmt + + + + + +### Docstring + +A PythonDefinition subclass representing a Python function +definition. + +:param name: The name of the definition. +:type name: str +:param args: The arguments. +:type args: list[PythonFunctionArgument] +:param returns: The return type of the function or class. +:type returns: Union[str, None] +:param doc: The docstring. +:type doc: Union[PythonDocstring, None] +:param decorators: The definition decorators. +:type decorators: list[str] + +:raises InvalidPythonIdentifierError: If the name is not a valid + Python identifier. + +## Class `PythonAsyncFunctionDefinition` + +A PythonDefinition subclass representing an asynchronous Python function +definition. + +### Base classes + +- `PythonFunctionDefinition` + + + + + + + +### Docstring + +A PythonDefinition subclass representing an asynchronous Python function +definition. + +:param name: The name of the definition. +:type name: str +:param args: The arguments. +:type args: list[PythonFunctionArgument] +:param returns: The return type of the function or class. +:type returns: Union[str, None] +:param doc: The docstring. +:type doc: Union[PythonDocstring, None] +:param decorators: The definition decorators. +:type decorators: list[str] + +:raises InvalidPythonIdentifierError: If the name is not a valid + Python identifier. + +## Class `PythonClassDefinition` + +A PythonDefinition subclass representing a Python class definition. + + +### Base classes + +- `PythonDefinition` + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, name: str, bases: list[str], doc: Union[PythonDocstring, None], decorators: list[str], body: list[PythonDefinition]) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `name` | `str` | normal | -- | -- | +| `bases` | `list[str]` | normal | -- | -- | +| `doc` | `Union[PythonDocstring, None]` | normal | -- | -- | +| `decorators` | `list[str]` | normal | -- | -- | +| `body` | `list[PythonDefinition]` | normal | -- | -- | + +#### Method `_arg_list` + +##### Method signature + +```python +_arg_list(self) -> tuple +``` + +##### Returns + +Return type: `tuple` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + +#### Method `from_node` + +From an AST node. + + +##### Method signature + +```python +from_node(cls, node: ast.stmt) -> PythonClassDefinition +``` + +##### Returns + +Return type: `PythonClassDefinition` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `cls` | -- | normal | -- | -- | +| `node` | `ast.stmt` | normal | -- | The AST node. | + + + +##### Decorators + +```python +classmethod +``` + + + +##### Docstring + +From an AST node. + +:param node: The AST node. +:type node: ast.stmt + + + + + +### Docstring + +A PythonDefinition subclass representing a Python class definition. + +:param name: The name of the definition. +:type name: str +:param bases: The base classes. +:type bases: list[str] +:param doc: The docstring. +:type doc: Union[PythonDocstring, None] +:param decorators: The definition decorators. +:type decorators: list[str] +:param body: +:type body: list[PythonDefinition] + +:raises InvalidPythonIdentifierError: If the name is not a valid + Python identifier. \ No newline at end of file diff --git a/docs/reference/jcloud_docsgen/core/python/docstrings.md b/docs/reference/jcloud_docsgen/core/python/docstrings.md new file mode 100644 index 0000000..1d716ef --- /dev/null +++ b/docs/reference/jcloud_docsgen/core/python/docstrings.md @@ -0,0 +1,113 @@ +# Module `jcloud_docsgen.core.python.docstrings` + +## Class `PythonDocstring` + +Represents a Python docstring. + + + + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, docstring: str) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `docstring` | `str` | normal | -- | -- | + +#### Method `__repr__` + +##### Method signature + +```python +__repr__(self) -> str +``` + +##### Returns + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + +#### Method `__eq__` + +##### Method signature + +```python +__eq__(self, value) -> bool +``` + +##### Returns + +Return type: `bool` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `value` | -- | normal | -- | -- | + +#### Method `parse` + +Parses the docstring. + + +##### Method signature + +```python +parse(self) -> docstring_parser.Docstring +``` + +##### Returns + +The parsed docstring. + +Return type: `docstring_parser.Docstring` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Parses the docstring. + +:return: The parsed docstring. +:rtype: docstring_parser.Docstring + + + + + +### Docstring + +Represents a Python docstring. + +:param docstring: The docstring as a string. +:type docstring: str \ No newline at end of file diff --git a/docs/reference/jcloud_docsgen/core/python/namespaces.md b/docs/reference/jcloud_docsgen/core/python/namespaces.md new file mode 100644 index 0000000..065bafe --- /dev/null +++ b/docs/reference/jcloud_docsgen/core/python/namespaces.md @@ -0,0 +1,442 @@ +# Module `jcloud_docsgen.core.python.namespaces` + +## Class `PythonNamespace` + +The base class for all Python namespaces such as modules or packages. + + + + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, name: str) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `name` | `str` | normal | -- | -- | + +#### Method `__repr__` + +##### Method signature + +```python +__repr__(self) -> str +``` + +##### Returns + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + +### Docstring + +The base class for all Python namespaces such as modules or packages. + +:param name: The name of the namespace. +:type name: str + +## Class `PythonPackageNamespace` + +A subclass of ``PythonNamespace`` for Python package namespaces. + + +### Base classes + +- `PythonNamespace` + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, name: str, sub_namespaces: List[PythonNamespace]) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `name` | `str` | normal | -- | -- | +| `sub_namespaces` | `List[PythonNamespace]` | normal | -- | -- | + +#### Method `namespace` + +Returns the namespace object with a specific identifier, such as +``['package', 'subpackage', 'module']``. + +##### Method signature + +```python +namespace(self, sub_namespaces: List[str]) -> PythonNamespace +``` + +##### Returns + +The namespace. + +Return type: `PythonNamespace` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `sub_namespaces` | `List[str]` | normal | -- | The identifier of the namespace. | + +##### Exceptions + +| Exception | Description | +| --- | --- | +| `InvalidNamespaceError` | If the namespace identifier is invalid. | +| `NamespaceNotFoundError` | If the namespace does not exist. | + + + + + +##### Docstring + +Returns the namespace object with a specific identifier, such as +``['package', 'subpackage', 'module']``. + +:param sub_namespaces: The identifier of the namespace. +:type sub_namespaces: list[str] + +:raises InvalidNamespaceError: If the namespace identifier is + invalid. +:raises NamespaceNotFoundError: If the namespace does not exist. + +:return: The namespace. +:rtype: PythonNamespace + +#### Method `_sub_namespaces_names` + +Returns the names of all sub-namespaces of the specified package +namespace and keeps the package structure. + +##### Method signature + +```python +_sub_namespaces_names(self, package: PythonPackageNamespace) -> PythonPackageNamespaceDictType +``` + +##### Returns + +The names if all sub-namespaces. + +Return type: `PythonPackageNamespaceDictType` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `package` | `PythonPackageNamespace` | normal | -- | The package. | + + + + + + + +##### Docstring + +Returns the names of all sub-namespaces of the specified package +namespace and keeps the package structure. + +:param package: The package. +:type package: PythonPackageNamespace + +:return: The names if all sub-namespaces. +:rtype: PythonPackageNamespaceDictType + +#### Method `sub_namespace_names` + +Returns the names of all sub-namespaces and keeps the package +structure. + +##### Method signature + +```python +sub_namespace_names(self) -> PythonPackageNamespaceDictType +``` + +##### Returns + +The names if all sub-namespaces. + +Return type: `PythonPackageNamespaceDictType` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + + + +##### Docstring + +Returns the names of all sub-namespaces and keeps the package +structure. + +:return: The names if all sub-namespaces. +:rtype: PythonPackageNamespaceDictType + +#### Method `__eq__` + +##### Method signature + +```python +__eq__(self, value: PythonPackageNamespace) -> bool +``` + +##### Returns + +Return type: `bool` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `value` | `PythonPackageNamespace` | normal | -- | -- | + +#### Method `__repr__` + +##### Method signature + +```python +__repr__(self) -> str +``` + +##### Returns + +Return type: `str` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + +#### Method `__getitem__` + +Returns a namespace with the specified name. + + +##### Method signature + +```python +__getitem__(self, name: str) -> PythonNamespace +``` + +##### Returns + +The namespace + +Return type: `PythonNamespace` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `name` | `str` | normal | -- | The name of the namespace | + +##### Exceptions + +| Exception | Description | +| --- | --- | +| `NamespaceNotFoundError` | If the namespace does not exist. | + + + + + +##### Docstring + +Returns a namespace with the specified name. + +:param name: The name of the namespace +:type name: str + +:raises NamespaceNotFoundError: If the namespace does not exist. + +:return: The namespace +:rtype: PythonNamespace + +#### Method `add` + +Adds a namespace. + + +##### Method signature + +```python +add(self, namespace: PythonNamespace) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `namespace` | `PythonNamespace` | normal | -- | The namespace to add. | + +##### Exceptions + +| Exception | Description | +| --- | --- | +| `NamespaceExistsError` | If a namespace with the name of the namespace that is attempted to add already exists. | + + + + + +##### Docstring + +Adds a namespace. + +:param namespace: The namespace to add. +:type namespace: PythonNamespace + +:raises NamespaceExistsError: If a namespace with the name of the + namespace that is attempted to add + already exists. + +#### Method `sub_namespaces` + +##### Method signature + +```python +sub_namespaces(self) -> List[PythonNamespace] +``` + +##### Returns + +Return type: `List[PythonNamespace]` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + +##### Decorators + +```python +property +``` + + + + + +### Docstring + +A subclass of ``PythonNamespace`` for Python package namespaces. + +:param name: The name of the namespace. +:type name: str +:param sub_namespaces: The sub-namespaces. +:type sub_namespaces: list[PythonNamespace] + +## Class `PythonModuleNamespace` + +A subclass of ``PythonNamespace`` for Python module namespaces. + + +### Base classes + +- `PythonNamespace` + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, name: str) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `name` | `str` | normal | -- | -- | + +#### Method `__eq__` + +##### Method signature + +```python +__eq__(self, value: PythonModuleNamespace) -> bool +``` + +##### Returns + +Return type: `bool` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `value` | `PythonModuleNamespace` | normal | -- | -- | + + + + + +### Docstring + +A subclass of ``PythonNamespace`` for Python module namespaces. + +:param name: The name of the namespace. +:type name: str \ No newline at end of file diff --git a/docs/reference/jcloud_docsgen/exceptions.md b/docs/reference/jcloud_docsgen/exceptions.md new file mode 100644 index 0000000..657dd30 --- /dev/null +++ b/docs/reference/jcloud_docsgen/exceptions.md @@ -0,0 +1,253 @@ +# Module `jcloud_docsgen.exceptions` + +## Class `NamespaceError` + +Base class for namespace errors. + +### Base classes + +- `ValueError` + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, *args: object, namespace_identifier: str = '') -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `args` | `object` | vararg | -- | -- | +| `namespace_identifier` | `str` | keyword-only | `''` | -- | + +#### Method `__str__` + +##### Method signature + +```python +__str__(self) +``` + + + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + +### Docstring + +Base class for namespace errors. + +## Class `InvalidNamespaceError` + +### Base classes + +- `NamespaceError` + +## Class `NamespaceNotFoundError` + +### Base classes + +- `NamespaceError` + +## Class `NamespaceExistsError` + +### Base classes + +- `NamespaceError` + +## Class `PythonIdentifierError` + +Base class for Python identifier errors. + +### Base classes + +- `ValueError` + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, *args: object, identifier: str = '') -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `args` | `object` | vararg | -- | -- | +| `identifier` | `str` | keyword-only | `''` | -- | + +#### Method `__str__` + +##### Method signature + +```python +__str__(self) +``` + + + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + +### Docstring + +Base class for Python identifier errors. + +## Class `InvalidPythonIdentifierError` + +### Base classes + +- `PythonIdentifierError` + +## Class `PythonAnnotationError` + +Base class for Python annotation errors. + +### Base classes + +- `ValueError` + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, *args: object, annotation: str = '') -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `args` | `object` | vararg | -- | -- | +| `annotation` | `str` | keyword-only | `''` | -- | + +#### Method `__str__` + +##### Method signature + +```python +__str__(self) +``` + + + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + +### Docstring + +Base class for Python annotation errors. + +## Class `InvalidPythonAnnotationError` + +### Base classes + +- `PythonAnnotationError` + +## Class `PythonDefinitionError` + +Base class for Python definition errors. + +### Base classes + +- `ValueError` + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, *args: object, definition: str = '') -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `args` | `object` | vararg | -- | -- | +| `definition` | `str` | keyword-only | `''` | -- | + +#### Method `__str__` + +##### Method signature + +```python +__str__(self) +``` + + + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | + + + + + +### Docstring + +Base class for Python definition errors. + +## Class `PythonArgumentStructureError` + +### Base classes + +- `PythonDefinitionError` \ No newline at end of file diff --git a/docs/reference/jcloud_docsgen/utils.md b/docs/reference/jcloud_docsgen/utils.md new file mode 100644 index 0000000..28ea355 --- /dev/null +++ b/docs/reference/jcloud_docsgen/utils.md @@ -0,0 +1,335 @@ +# Module `jcloud_docsgen.utils` + +The utilities for jcloud_docsgen + +## Class `ExistingDirectory` + +pathlib.Path subclass that is a directory. + +ExistingDirectory represents a filesystem path but it also checks +whether the path exists and is not a file but a directory. It +inherits from pathlib.Path. + +### Base classes + +- `pathlib.Path` + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, path, *args, **kwargs) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `path` | -- | normal | -- | -- | +| `args` | -- | vararg | -- | -- | +| `kwargs` | -- | kwargs | -- | -- | + + + + + +### Docstring + +pathlib.Path subclass that is a directory. + +ExistingDirectory represents a filesystem path but it also checks +whether the path exists and is not a file but a directory. It +inherits from pathlib.Path. + +## Class `ExistingFile` + +pathlib.Path subclass that is a file. + +ExistingFile represents a filesystem path but it also checks whether +the path exists and is not a directory but a file. It inherits from +pathlib.Path. + +### Base classes + +- `pathlib.Path` + +### Body + +#### Constructor (method `__init__`) + +##### Method signature + +```python +__init__(self, path, *args, **kwargs) -> None +``` + +##### Returns + +Return type: `None` + +##### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `self` | -- | normal | -- | -- | +| `path` | -- | normal | -- | -- | +| `args` | -- | vararg | -- | -- | +| `kwargs` | -- | kwargs | -- | -- | + + + + + +### Docstring + +pathlib.Path subclass that is a file. + +ExistingFile represents a filesystem path but it also checks whether +the path exists and is not a directory but a file. It inherits from +pathlib.Path. + +## Function `_quote` + +Quotes a string. + + +### Function signature + +```python +_quote(string: str, quotation_mark: str) -> str +``` + +### Returns + +The quoted string + +Return type: `str` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `string` | `str` | normal | -- | The string to quote | +| `quotation_mark` | `str` | normal | -- | The quotation mark | + + + + + + + +### Docstring + +Quotes a string. + +:param string: The string to quote +:type string: str +:param quotation_mark: The quotation mark +:type quotation_mark: str + +:return: The quoted string +:rtype: str + +## Function `human_readable_list` + +Generates a human-readable list from a list. + + +### Function signature + +```python +human_readable_list(ls: list, final_separator: str = 'and', quotation_mark: str = '') -> str +``` + +### Returns + +The human-readable list. + +Return type: `str` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `ls` | `list` | normal | -- | The list. | +| `final_separator` | `str` | normal | `'and'` | The seperator between the last and the second-to-last element of the list. Default is 'and'. | +| `quotation_mark` | `str` | normal | `''` | The characters that are inserted before and after an element. Default is ''. | + + + + + + + +### Docstring + +Generates a human-readable list from a list. + +:param ls: The list. +:type ls: list +:param final_separator: The seperator between the last and the + second-to-last element of the list. Default + is 'and'. +:type final_separator: str +:param quotation_mark: The characters that are inserted before and + after an element. Default is ''. + +:return: The human-readable list. +:rtype: str + +## Function `_list_type_names` + +Converts a list of types into a list of their names (``__name__`` +attribute) + +### Function signature + +```python +_list_type_names(types: list[type]) -> list[str] +``` + +### Returns + +The list of the names of the types + +Return type: `list[str]` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `types` | `list[type]` | normal | -- | The list of types | + + + + + + + +### Docstring + +Converts a list of types into a list of their names (``__name__`` +attribute) + +:param types: The list of types +:type types: list[type] + +:return: The list of the names of the types +:rtype: list[str] + +## Function `assert_that_is_instance` + +### Function signature + +```python +assert_that_is_instance(obj: object, class_or_tuple: Union[type, types.UnionType, tuple[type, ...]]) -> None +``` + +### Returns + +Return type: `None` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `obj` | `object` | normal | -- | -- | +| `class_or_tuple` | `Union[type, types.UnionType, tuple[type, ...]]` | normal | -- | -- | + +## Function `non_empty_str` + +Returns the value or ``None``. + +Returns the value if it is not empty and not `Ǹone``; otherwise, +returns ``None``. +Please note: values are stripped, i. e. if the value consists only + of spaces, it is also considered empty. + +### Function signature + +```python +non_empty_str(value: Union[str, None]) -> Union[str, None] +``` + +### Returns + +The value or ``None``. + +Return type: `Union[str, None]` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `value` | `Union[str, None]` | normal | -- | The value. | + + + + + + + +### Docstring + +Returns the value or ``None``. + +Returns the value if it is not empty and not `Ǹone``; otherwise, +returns ``None``. +Please note: values are stripped, i. e. if the value consists only + of spaces, it is also considered empty. + +:param value: The value. +:type value: Union[str, None] + +:return: The value or ``None``. +:rtype: Union[str, None] + +## Function `get_relative_path_segments` + +Returns the path segments relative to ``root``. + + +### Function signature + +```python +get_relative_path_segments(path: pathlib.Path, root: pathlib.Path) -> list[str] +``` + +### Returns + +The path segments relative to ``root``. + +Return type: `list[str]` + +### Parameters + +| Parameter | Type | Kind | Default value | Description | +| --- | --- | --- | --- | --- | +| `path` | `pathlib.Path` | normal | -- | The path. | +| `root` | `pathlib.Path` | normal | -- | The root path. | + + + + + + + +### Docstring + +Returns the path segments relative to ``root``. + +:param path: The path. +:type path: pathlib.Path +:param root: The root path. +:type root: pathlib.Path + +:return: The path segments relative to ``root``. +:rtype: list[str] \ No newline at end of file