docs(changelog): add project directory structure entry

Added an entry that the implicit Python project directory
structure assumptions have been removed to the changelog.

.gitea/workflows/generate-api-reference.yml

@@ -16,7 +16,7 @@ name: Generate API reference
 
 on:
   push:
-    branches:
+    branch:
       - main
 
 permissions:
@@ -39,7 +39,8 @@ jobs:
 
       - name: Generate documentation
         run: |
-          jcloud-docsgen python -T -f -o docs/reference ./src
+          rm -rf docs/reference
+          jcloud-docsgen python -T -o docs/reference .
 
       - name: Commit and push
         run: |
@@ -48,7 +49,7 @@ jobs:
 
           git add docs/reference
 
-          if git diff --cached --quiet; then
+          if git diff --chached --quit; then
             echo "No changes"
             exit 0
           fi

NOTICE

@@ -0,0 +1,41 @@
+Third-Party Notices
+===================
+
+This software uses the following third-party libraries. Full license texts are available in the 'licenses/' directory.
+
+1. docstring-parser 0.17.0
+   Author: Marcin Kurczewski
+   License: MIT License
+   See licenses/docstring-parser.txt for full license text.
+
+2. iniconfig 2.3.0
+   Author: Holger Krekel and others
+   License: MIT License
+   See licenses/iniconfig.txt for full license text.
+
+3. packaging 26.0
+   Author: Donald Stufft and individual contributors
+   License: Apache License 2.0   
+   URL: None
+   See licenses/packaging.txt for full license text.
+
+4. pluggy 1.6.0
+   Author: Holger Krekel
+   License: MIT License
+   See licenses/pluggy.txt for full license text.
+
+5. pygments 2.18.0
+   Author: Georg Brandl, Tim Hatch, Armin Ronacher, Others
+   License: BSD-2-Clause
+   See licenses/pygments.txt for full license text.
+
+6. pytest 9.0.2
+   Author: Holger Krekel, Bruno Oliveira, Ronny Pfannschmidt, Floris Bruynooghe, Brianna Laugher, Florian Bruhin, Others
+   License: MIT License
+   See licenses/pytest.txt for full license text.
+
+7. pytest-expectdir 1.2.0
+   Author: Léo Falventin Hauchecorne
+   License: MIT
+   URL: https://github.com/hl037/pytest-expectdir
+   See licenses/pytest-expectdir.txt for full license text.

docs/CHANGELOG.md

@@ -1,43 +1,18 @@
 # Changelog
 
-## [0.2.3] - 2026-10-21
-
-### Fixed
-
-- Escape sequences for pipe characters in values of Markdown table cells
-
-## [0.2.2] - 2026-10-14
-
-### Fixed
-
-- Import error in Python <3.13 which prevented the tool from running and made it unusuable in Python <3.13
-
-## [0.2.1] - 2026-10-06
-
-### Fixed
-
-- Python namespace name conflict when package and module have the same name
-- Internal namespace name error which occured when generating Python documentation with `.` as the project directory
-- Ignore Python namespaces with invalid names during documentation generation
-
-### Changed
-
-- Stricter Python namespace name validation
-
-## [0.2.0] - 2026-09-28
+## [Unreleased]
 
 ### Added
 
 - CLI for `jcloud-docsgen` that can be called without `python3 -m ...`
 - CI pipeline to generate API reference on every push or merge on `main`
 - Python generator output directory creation
-- Protection against accidental overwriting of the output directory
 
 ### Changed
 
 - Replaced the installation instructions, which used the old registry, with a reference to the Gitea Package Registry in README
 - Made Python function signatures (argument default values) compliant with PEP 8
-- Removed implicit Python project directory structure assumptions
+- Removed implicit project directory structure assumptions
 
 ### Deprecated
 

docs/reference/jcloud_docsgen/__init__.md

@@ -1 +0,0 @@
-# Module `jcloud_docsgen.__init__`

docs/reference/jcloud_docsgen/__main__.md

@@ -1 +0,0 @@
-# Module `jcloud_docsgen.__main__`

docs/reference/jcloud_docsgen/cli/__init__.md

@@ -1 +0,0 @@
-# Module `jcloud_docsgen.cli.__init__`

docs/reference/jcloud_docsgen/cli/cli.md

@@ -1,107 +0,0 @@
-# Module `jcloud_docsgen.cli.cli`
-
-The command line interface
-
-## Function `existing_directory`
-
-### Function signature
-
-```python
-existing_directory(path: str) -> pathlib.Path
-```
-
-### Returns
-
-Return type: `pathlib.Path`
-
-### Parameters
-
-| Parameter | Type | Kind | Default value | Description |
-| --- | --- | --- | --- | --- |
-| `path` | `str` | normal | -- | -- |
-
-## Function `error`
-
-Shows an error message and returns the exit code.
-
-
-### Function signature
-
-```python
-error(message: str, exit_code: int = 1)
-```
-
-
-
-### Parameters
-
-| Parameter | Type | Kind | Default value | Description |
-| --- | --- | --- | --- | --- |
-| `message` | `str` | normal | -- | The error message to show. |
-| `exit_code` | `int` | normal | `1` | The exit code. |
-
-
-
-
-
-
-
-### Docstring
-
-Shows an error message and returns the exit code.
-
-:param message: The error message to show.
-:type message: str
-:param exit_code: The exit code.
-:type exit_code: int
-
-## Function `create_argument_parser`
-
-Prepares a parser to parse the command-line arguments using
-argparse.
-
-### Function signature
-
-```python
-create_argument_parser() -> argparse.ArgumentParser
-```
-
-### Returns
-
-The parser.
-
-Return type: `argparse.ArgumentParser`
-
-
-
-
-
-
-
-
-
-### Docstring
-
-Prepares a parser to parse the command-line arguments using
-argparse.
-
-:return: The parser.
-:rtype: argparse.ArgumentParser
-
-## Function `main`
-
-### Function signature
-
-```python
-main(argv=None) -> int
-```
-
-### Returns
-
-Return type: `int`
-
-### Parameters
-
-| Parameter | Type | Kind | Default value | Description |
-| --- | --- | --- | --- | --- |
-| `argv` | -- | normal | `None` | -- |

docs/reference/jcloud_docsgen/cli/languages/__init__.md

@@ -1 +0,0 @@
-# Module `jcloud_docsgen.cli.languages.__init__`

docs/reference/jcloud_docsgen/cli/languages/python.md

@@ -1,156 +0,0 @@
-# Module `jcloud_docsgen.cli.languages.python`
-
-## Function `parse_sections_list`
-
-Returns a Python definition documentation sections list from the
-sections list to be included and the sections list to be excluded.
-These lists both consist of the sections as strings which contain
-the section name.
-
-### Function signature
-
-```python
-parse_sections_list(include_sections: list[str] | None = None, exclude_sections: list[str] = []) -> PythonDefinitionDocumentationIncludeSections
-```
-
-### Returns
-
-The Python definition documentation sections object.
-
-Return type: `PythonDefinitionDocumentationIncludeSections`
-
-### Parameters
-
-| Parameter | Type | Kind | Default value | Description |
-| --- | --- | --- | --- | --- |
-| `include_sections` | `list[str] | None` | normal | `None` | The list of sections to be included. |
-| `exclude_sections` | `list[str]` | normal | `[]` | The list of sections to be excluded. |
-
-
-
-
-
-
-
-### Docstring
-
-Returns a Python definition documentation sections list from the
-sections list to be included and the sections list to be excluded.
-These lists both consist of the sections as strings which contain
-the section name.
-
-:param include_sections: The list of sections to be included.
-:type include_sections: list[str] | None
-:param exclude_sections: The list of sections to be excluded.
-:type exclude_sections: list[str]
-
-:return: The Python definition documentation sections object.
-:rtype: PythonDefinitionDocumentationIncludeSections
-
-## Function `_generate`
-
-Generates the documentation for a Python project.
-
-
-### Function signature
-
-```python
-_generate(project_directory: pathlib.Path, output_directory: pathlib.Path, *, include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(), allow_html: bool = False, allow_tables: bool = False, force: bool = False) -> None
-```
-
-### Returns
-
-Return type: `None`
-
-### Parameters
-
-| Parameter | Type | Kind | Default value | Description |
-| --- | --- | --- | --- | --- |
-| `project_directory` | `pathlib.Path` | normal | -- | The project directory. |
-| `output_directory` | `pathlib.Path` | normal | -- | The output directory. |
-| `include_sections` | `PythonDefinitionDocumentationIncludeSections` | keyword-only | `PythonDefinitionDocumentationIncludeSections()` | The sections to be included in the documentation. |
-| `allow_html` | `bool` | keyword-only | `False` | Indicates whether HTML is allowed to appear in the generated documentation. |
-| `allow_tables` | `bool` | keyword-only | `False` | Indicates whether Markdown tables are allowed. Warning: Markdown tables are not CommonMark. |
-| `force` | `bool` | keyword-only | `False` | Indicates whether the output directory shall be overwritten if it is not empty. |
-
-
-
-
-
-
-
-### Docstring
-
-Generates the documentation for a Python project.
-
-:param project_directory: The project directory.
-:type project_directory: pathlib.Path
-:param output_directory: The output directory.
-:type output_directory: pathlib.Path
-:param include_sections: The sections to be included in the
-                         documentation.
-:type include_sections: PythonDefinitionDocumentationIncludeSections
-:param allow_html: Indicates whether HTML is allowed to appear in
-                   the generated documentation.
-:type allow_html: bool
-:param allow_tables: Indicates whether Markdown tables are allowed.
-                     Warning: Markdown tables are not CommonMark.
-:param force: Indicates whether the output directory shall be
-              overwritten if it is not empty.
-:type force: bool
-
-## Function `generate`
-
-Generates the documentation for a Python project.
-
-
-### Function signature
-
-```python
-generate(project_directory: pathlib.Path, output_directory: pathlib.Path, *, include_sections: list[str] | None = None, exclude_sections: list[str] = [], allow_html: bool = False, allow_tables: bool = False, force: bool = False) -> None
-```
-
-### Returns
-
-Return type: `None`
-
-### Parameters
-
-| Parameter | Type | Kind | Default value | Description |
-| --- | --- | --- | --- | --- |
-| `project_directory` | `pathlib.Path` | normal | -- | The project directory. |
-| `output_directory` | `pathlib.Path` | normal | -- | The output directory. |
-| `include_sections` | `list[str] | None` | keyword-only | `None` | The sections to be included in the documentation. |
-| `exclude_sections` | `list[str]` | keyword-only | `[]` | The sections to be excluded in the documentation. |
-| `allow_html` | `bool` | keyword-only | `False` | Indicates whether HTML is allowed to appear in the generated documentation. |
-| `allow_tables` | `bool` | keyword-only | `False` | Indicates whether Markdown tables are allowed. Warning: Markdown tables are not CommonMark. |
-| `force` | `bool` | keyword-only | `False` | Indicates whether the output directory shall be overwritten if it is not empty. |
-
-
-
-
-
-
-
-### Docstring
-
-Generates the documentation for a Python project.
-
-:param project_directory: The project directory.
-:type project_directory: pathlib.Path
-:param output_directory: The output directory.
-:type output_directory: pathlib.Path
-:param include_sections: The sections to be included in the
-                         documentation.
-:type include_sections: list[str] | None
-:param exclude_sections: The sections to be excluded in the
-                         documentation.
-:type exclude_sections: list[str]
-:param allow_html: Indicates whether HTML is allowed to appear in
-                   the generated documentation.
-:type allow_html: bool
-:param allow_tables: Indicates whether Markdown tables are allowed.
-                     Warning: Markdown tables are not CommonMark.
-:param force: Indicates whether the output directory shall be
-              overwritten if it is not empty.
-:type force: bool

docs/reference/jcloud_docsgen/core/__init__.md

@@ -1 +0,0 @@
-# Module `jcloud_docsgen.core.__init__`

docs/reference/jcloud_docsgen/core/python/__init__.md

@@ -1 +0,0 @@
-# Module `jcloud_docsgen.core.python.__init__`

docs/reference/jcloud_docsgen/core/python/_core.md

@@ -47,12 +47,12 @@ keyword-only arguments and the var-keyword-argument if there is one.
 ### Function signature
 
 ```python
-_group_argument_list(argument_list: list[PythonFunctionArgument]) -> _Arguments
+_group_argument_list(argument_list: list[PythonFunctionArgument]) -> tuple[list[PythonFunctionArgument], list[PythonFunctionArgument], Union[PythonFunctionArgument, None], list[PythonFunctionArgument], Union[PythonFunctionArgument, None]]
 ```
 
 ### Returns
 
-Return type: `_Arguments`
+Return type: `tuple[list[PythonFunctionArgument], list[PythonFunctionArgument], Union[PythonFunctionArgument, None], list[PythonFunctionArgument], Union[PythonFunctionArgument, None]]`
 
 ### Parameters
 
@@ -75,7 +75,7 @@ keyword-only arguments and the var-keyword-argument if there is one.
 :param argument_list: The argument list.
 :type argument_list: list[PythonFunctionArgument]
 
-:rtype: _Arguments
+:rtype: tuple[list[PythonFunctionArgument], list[PythonFunctionArgument], Union[PythonFunctionArgument, None], list[PythonFunctionArgument], Union[PythonFunctionArgument, None]]
 
 ## Function `_signature_argument_list`
 
@@ -116,6 +116,106 @@ Returns a list of the arguments as strings for a function signature.
 :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.
@@ -124,7 +224,7 @@ Checks whether the docstring is a docstring or an empty docstring.
 ### Function signature
 
 ```python
-_is_docstring(docstring: str | PythonDocstring | None) -> bool
+_is_docstring(docstring: Union[str, PythonDocstring, None]) -> bool
 ```
 
 ### Returns
@@ -137,7 +237,7 @@ Return type: `bool`
 
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
-| `docstring` | `str | PythonDocstring | None` | normal | -- | The docstring. |
+| `docstring` | `Union[str, PythonDocstring, None]` | normal | -- | The docstring. |
 
 
 
@@ -150,7 +250,7 @@ Return type: `bool`
 Checks whether the docstring is a docstring or an empty docstring.
 
 :param docstring: The docstring.
-:type docstring: str | PythonDocstring | None
+:type docstring: Union[str, PythonDocstring, None]
 
 :return: Whether there is a docstring.
 :rtype: bool
@@ -875,7 +975,7 @@ A documentation generator for a Python module.
 ##### Method signature
 
 ```python
-__init__(self, module_path: pathlib.Path, src_directory: pathlib.Path | None = None, include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(), **kwargs) -> None
+__init__(self, module_path: ExistingFile, src_directory: Union[ExistingDirectory, None] = None, include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(), **kwargs) -> None
 ```
 
 ##### Returns
@@ -887,8 +987,8 @@ Return type: `None`
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
 | `self` | -- | normal | -- | -- |
-| `module_path` | `pathlib.Path` | normal | -- | -- |
-| `src_directory` | `pathlib.Path | None` | normal | `None` | -- |
+| `module_path` | `ExistingFile` | normal | -- | -- |
+| `src_directory` | `Union[ExistingDirectory, None]` | normal | `None` | -- |
 | `include_sections` | `PythonDefinitionDocumentationIncludeSections` | normal | `PythonDefinitionDocumentationIncludeSections()` | -- |
 | `kwargs` | -- | kwargs | -- | -- |
 
@@ -1025,11 +1125,11 @@ Generates the documentation in the markdown format.
 A documentation generator for a Python module.
 
 :param module_path: The path of the module file.
-:type module_path: pathlib.Path
+: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: pathlib.Path | None
+: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``.
@@ -1097,7 +1197,7 @@ The class for the documentation generator.
 ##### Method signature
 
 ```python
-__init__(self, project_directory: pathlib.Path, docs_directory: pathlib.Path, include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(), **kwargs) -> None
+__init__(self, project_directory: ExistingDirectory, docs_directory: ExistingDirectory, include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(), **kwargs) -> None
 ```
 
 ##### Returns
@@ -1109,8 +1209,8 @@ Return type: `None`
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
 | `self` | -- | normal | -- | -- |
-| `project_directory` | `pathlib.Path` | normal | -- | -- |
-| `docs_directory` | `pathlib.Path` | normal | -- | -- |
+| `project_directory` | `ExistingDirectory` | normal | -- | -- |
+| `docs_directory` | `ExistingDirectory` | normal | -- | -- |
 | `include_sections` | `PythonDefinitionDocumentationIncludeSections` | normal | `PythonDefinitionDocumentationIncludeSections()` | -- |
 | `kwargs` | -- | kwargs | -- | -- |
 
@@ -1141,14 +1241,14 @@ Returns the project as a namespace.
 ##### Method signature
 
 ```python
-namespace(self) -> PythonPackageNamespace
+namespace(self) -> list[PythonPackageNamespace]
 ```
 
 ##### Returns
 
 The project as a namespace.
 
-Return type: `PythonPackageNamespace`
+Return type: `list[PythonPackageNamespace]`
 
 ##### Parameters
 
@@ -1167,7 +1267,7 @@ Return type: `PythonPackageNamespace`
 Returns the project as a namespace.
 
 :return: The project as a namespace.
-:rtype: PythonPackageNamespace:
+:rtype: list[PythonPackageNamespace]
 
 #### Method `generate_documentation`
 
@@ -1177,7 +1277,7 @@ documentation directory.
 ##### Method signature
 
 ```python
-generate_documentation(self, force: bool = False) -> None
+generate_documentation(self) -> None
 ```
 
 ##### Returns
@@ -1189,13 +1289,8 @@ Return type: `None`
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
 | `self` | -- | normal | -- | -- |
-| `force` | `bool` | normal | `False` | Indicates whether existing contents of the output directory shall be overwritten. If ``True``, all contents of the output directory will be deleted first. |
 
-##### Exceptions
 
-| Exception | Description |
-| --- | --- |
-| `DirectoryNotEmptyError` | If ``force`` is ``False`` and the output directory is not empty. |
 
 
 
@@ -1206,16 +1301,6 @@ Return type: `None`
 Generates the full project documentation and writes it to the
 documentation directory.
 
-:param force: Indicates whether existing contents of the output
-              directory shall be overwritten. If ``True``, all
-              contents of the output directory will be deleted
-              first.
-:type force: bool
-
-:raises DirectoryNotEmptyError: If ``force`` is ``False`` and
-                                the output directory is not
-                                empty.
-
 
 
 
@@ -1225,9 +1310,9 @@ documentation directory.
 The class for the documentation generator.
 
 :param project_directory: The directory of the project.
-:type project_directory: pathlib.Path
+:type project_directory: ExistingDirectory
 :param docs_directory: The directory for the generated documentation.
-:type docs_directory: pathlib.Path
+: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``.

docs/reference/jcloud_docsgen/core/python/arguments.md

@@ -20,7 +20,7 @@ Represents an argument of a Python function.
 ##### Method signature
 
 ```python
-__init__(self, name: str, kind: PythonArgumentKind, default: str | None, annotation: str | None) -> None
+__init__(self, name: str, kind: PythonArgumentKind, default: Union[str, None], annotation: Union[str, None]) -> None
 ```
 
 ##### Returns
@@ -34,8 +34,8 @@ Return type: `None`
 | `self` | -- | normal | -- | -- |
 | `name` | `str` | normal | -- | -- |
 | `kind` | `PythonArgumentKind` | normal | -- | -- |
-| `default` | `str | None` | normal | -- | -- |
-| `annotation` | `str | None` | normal | -- | -- |
+| `default` | `Union[str, None]` | normal | -- | -- |
+| `annotation` | `Union[str, None]` | normal | -- | -- |
 
 #### Method `__eq__`
 
@@ -123,9 +123,9 @@ Represents an argument of a Python function.
 :param kind: The kind of the argument.
 :type kind: ArgumentKind
 :param default: The default value of the argument.
-:type default: str | None
+:type default: Union[str, None]
 :param annotation: The type annotation of the argument.
-:type annotation: str | None
+:type annotation: Union[str, None]
 
 ## Class `PythonASTArgumentsListParser`
 

docs/reference/jcloud_docsgen/core/python/definitions.md

@@ -8,20 +8,20 @@ not ``None``.
 ### Function signature
 
 ```python
-_python_docstring(doc: str | None) -> PythonDocstring | None
+_python_docstring(doc: Union[str, None]) -> Union[PythonDocstring, None]
 ```
 
 ### Returns
 
 The PythonDocstring object or ``None``.
 
-Return type: `PythonDocstring | None`
+Return type: `Union[PythonDocstring, None]`
 
 ### Parameters
 
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
-| `doc` | `str | None` | normal | -- | The docstring. |
+| `doc` | `Union[str, None]` | normal | -- | The docstring. |
 
 
 
@@ -35,10 +35,10 @@ Returns the PythonDocstring object if the docstring is a string and
 not ``None``.
 
 :param doc: The docstring.
-:type doc: str | None
+:type doc: Union[str, None]
 
 :return: The PythonDocstring object or ``None``.
-:rtype: PythonDocstring | None
+:rtype: Union[PythonDocstring, None]
 
 ## Class `PythonDefinition`
 
@@ -54,7 +54,7 @@ function definition) classes.
 ##### Method signature
 
 ```python
-__init__(self, name: str, doc: PythonDocstring | None, decorators: list[str]) -> None
+__init__(self, name: str, doc: Union[PythonDocstring, None], decorators: list[str]) -> None
 ```
 
 ##### Returns
@@ -67,7 +67,7 @@ Return type: `None`
 | --- | --- | --- | --- | --- |
 | `self` | -- | normal | -- | -- |
 | `name` | `str` | normal | -- | -- |
-| `doc` | `PythonDocstring | None` | normal | -- | -- |
+| `doc` | `Union[PythonDocstring, None]` | normal | -- | -- |
 | `decorators` | `list[str]` | normal | -- | -- |
 
 #### Method `_arg_list`
@@ -176,7 +176,7 @@ function definition) classes.
 :param name: The name of the definition.
 :type name: str
 :param doc: The docstring.
-:type doc: PythonDocstring | None
+:type doc: Union[PythonDocstring, None]
 :param decorators: The definition decorators.
 :type decorators: list[str]
 
@@ -199,7 +199,7 @@ definition.
 ##### Method signature
 
 ```python
-__init__(self, name: str, args: list[PythonFunctionArgument], returns: str | None, doc: PythonDocstring | None, decorators: list[str]) -> None
+__init__(self, name: str, args: list[PythonFunctionArgument], returns: Union[str, None], doc: Union[PythonDocstring, None], decorators: list[str]) -> None
 ```
 
 ##### Returns
@@ -213,8 +213,8 @@ Return type: `None`
 | `self` | -- | normal | -- | -- |
 | `name` | `str` | normal | -- | -- |
 | `args` | `list[PythonFunctionArgument]` | normal | -- | -- |
-| `returns` | `str | None` | normal | -- | -- |
-| `doc` | `PythonDocstring | None` | normal | -- | -- |
+| `returns` | `Union[str, None]` | normal | -- | -- |
+| `doc` | `Union[PythonDocstring, None]` | normal | -- | -- |
 | `decorators` | `list[str]` | normal | -- | -- |
 
 #### Method `_arg_list`
@@ -288,9 +288,9 @@ definition.
 :param args: The arguments.
 :type args: list[PythonFunctionArgument]
 :param returns: The return type of the function or class.
-:type returns: str | None
+:type returns: Union[str, None]
 :param doc: The docstring.
-:type doc: PythonDocstring | None
+:type doc: Union[PythonDocstring, None]
 :param decorators: The definition decorators.
 :type decorators: list[str]
 
@@ -322,9 +322,9 @@ definition.
 :param args: The arguments.
 :type args: list[PythonFunctionArgument]
 :param returns: The return type of the function or class.
-:type returns: str | None
+:type returns: Union[str, None]
 :param doc: The docstring.
-:type doc: PythonDocstring | None
+:type doc: Union[PythonDocstring, None]
 :param decorators: The definition decorators.
 :type decorators: list[str]
 
@@ -347,7 +347,7 @@ A PythonDefinition subclass representing a Python class definition.
 ##### Method signature
 
 ```python
-__init__(self, name: str, bases: list[str], doc: PythonDocstring | None, decorators: list[str], body: list[PythonDefinition]) -> None
+__init__(self, name: str, bases: list[str], doc: Union[PythonDocstring, None], decorators: list[str], body: list[PythonDefinition]) -> None
 ```
 
 ##### Returns
@@ -361,7 +361,7 @@ Return type: `None`
 | `self` | -- | normal | -- | -- |
 | `name` | `str` | normal | -- | -- |
 | `bases` | `list[str]` | normal | -- | -- |
-| `doc` | `PythonDocstring | None` | normal | -- | -- |
+| `doc` | `Union[PythonDocstring, None]` | normal | -- | -- |
 | `decorators` | `list[str]` | normal | -- | -- |
 | `body` | `list[PythonDefinition]` | normal | -- | -- |
 
@@ -435,7 +435,7 @@ A PythonDefinition subclass representing a Python class definition.
 :param bases: The base classes.
 :type bases: list[str]
 :param doc: The docstring.
-:type doc: PythonDocstring | None
+:type doc: Union[PythonDocstring, None]
 :param decorators: The definition decorators.
 :type decorators: list[str]
 :param body:

docs/reference/jcloud_docsgen/core/python/namespaces.md

@@ -1,45 +1,5 @@
 # Module `jcloud_docsgen.core.python.namespaces`
 
-## Function `validate_namespace_name`
-
-Checks whether a namespace name is valid. Namespace names are valid
-if they contain no dots and are valid Python identifiers.
-
-### Function signature
-
-```python
-validate_namespace_name(name: str) -> bool
-```
-
-### Returns
-
-Whether the namespace name is valid.
-
-Return type: `bool`
-
-### Parameters
-
-| Parameter | Type | Kind | Default value | Description |
-| --- | --- | --- | --- | --- |
-| `name` | `str` | normal | -- | The namespace name to validate. |
-
-
-
-
-
-
-
-### Docstring
-
-Checks whether a namespace name is valid. Namespace names are valid
-if they contain no dots and are valid Python identifiers.
-
-:param name: The namespace name to validate.
-:type name: str
-
-:returns: Whether the namespace name is valid.
-:rtype: bool
-
 ## Class `PythonNamespace`
 
 The base class for all Python namespaces such as modules or packages.
@@ -97,8 +57,6 @@ The base class for all Python namespaces such as modules or packages.
 :param name: The name of the namespace.
 :type name: str
 
-:raises InvalidNamespaceError: If the namespace  name is invalid.
-
 ## Class `PythonPackageNamespace`
 
 A subclass of ``PythonNamespace`` for Python package namespaces.
@@ -115,7 +73,7 @@ A subclass of ``PythonNamespace`` for Python package namespaces.
 ##### Method signature
 
 ```python
-__init__(self, name: str, sub_namespaces: list[PythonNamespace]) -> None
+__init__(self, name: str, sub_namespaces: List[PythonNamespace]) -> None
 ```
 
 ##### Returns
@@ -128,7 +86,7 @@ Return type: `None`
 | --- | --- | --- | --- | --- |
 | `self` | -- | normal | -- | -- |
 | `name` | `str` | normal | -- | -- |
-| `sub_namespaces` | `list[PythonNamespace]` | normal | -- | -- |
+| `sub_namespaces` | `List[PythonNamespace]` | normal | -- | -- |
 
 #### Method `namespace`
 
@@ -138,7 +96,7 @@ Returns the namespace object with a specific identifier, such as
 ##### Method signature
 
 ```python
-namespace(self, sub_namespaces: list[str]) -> PythonNamespace
+namespace(self, sub_namespaces: List[str]) -> PythonNamespace
 ```
 
 ##### Returns
@@ -152,7 +110,7 @@ Return type: `PythonNamespace`
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
 | `self` | -- | normal | -- | -- |
-| `sub_namespaces` | `list[str]` | normal | -- | The identifier of the namespace. |
+| `sub_namespaces` | `List[str]` | normal | -- | The identifier of the namespace. |
 
 ##### Exceptions
 
@@ -389,12 +347,12 @@ Adds a namespace.
 ##### Method signature
 
 ```python
-sub_namespaces(self) -> list[PythonNamespace]
+sub_namespaces(self) -> List[PythonNamespace]
 ```
 
 ##### Returns
 
-Return type: `list[PythonNamespace]`
+Return type: `List[PythonNamespace]`
 
 ##### Parameters
 
@@ -423,8 +381,6 @@ A subclass of ``PythonNamespace`` for Python package namespaces.
 :param sub_namespaces: The sub-namespaces.
 :type sub_namespaces: list[PythonNamespace]
 
-:raises InvalidNamespaceError: If the namespace name is invalid.
-
 ## Class `PythonModuleNamespace`
 
 A subclass of ``PythonNamespace`` for Python module namespaces.

docs/reference/jcloud_docsgen/exceptions.md

@@ -251,40 +251,3 @@ Base class for Python definition errors.
 ### Base classes
 
 - `PythonDefinitionError`
-
-## Class `DirectoryNotEmptyError`
-
-Directory is not empty.
-
-### Base classes
-
-- `OSError`
-
-### Body
-
-#### Constructor (method `__init__`)
-
-##### Method signature
-
-```python
-__init__(self, filename: str | None = None) -> None
-```
-
-##### Returns
-
-Return type: `None`
-
-##### Parameters
-
-| Parameter | Type | Kind | Default value | Description |
-| --- | --- | --- | --- | --- |
-| `self` | -- | normal | -- | -- |
-| `filename` | `str | None` | normal | `None` | -- |
-
-
-
-
-
-### Docstring
-
-Directory is not empty.

docs/reference/jcloud_docsgen/utils.md

@@ -37,11 +37,7 @@ Return type: `None`
 | `args` | -- | vararg | -- | -- |
 | `kwargs` | -- | kwargs | -- | -- |
 
-### Decorators
 
-```python
-deprecated('Use pathlib.Path instead.')
-```
 
 
 
@@ -88,11 +84,7 @@ Return type: `None`
 | `args` | -- | vararg | -- | -- |
 | `kwargs` | -- | kwargs | -- | -- |
 
-### Decorators
 
-```python
-deprecated('Use pathlib.Path instead.')
-```
 
 
 
@@ -238,7 +230,7 @@ attribute)
 ### Function signature
 
 ```python
-assert_that_is_instance(obj: object, class_or_tuple: type | types.UnionType | tuple[type, ...]) -> None
+assert_that_is_instance(obj: object, class_or_tuple: Union[type, types.UnionType, tuple[type, ...]]) -> None
 ```
 
 ### Returns
@@ -250,7 +242,7 @@ Return type: `None`
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
 | `obj` | `object` | normal | -- | -- |
-| `class_or_tuple` | `type | types.UnionType | tuple[type, ...]` | normal | -- | -- |
+| `class_or_tuple` | `Union[type, types.UnionType, tuple[type, ...]]` | normal | -- | -- |
 
 ## Function `non_empty_str`
 
@@ -264,20 +256,20 @@ Please note: values are stripped, i. e. if the value consists only
 ### Function signature
 
 ```python
-non_empty_str(value: str | None) -> str | None
+non_empty_str(value: Union[str, None]) -> Union[str, None]
 ```
 
 ### Returns
 
 The value or ``None``.
 
-Return type: `str | None`
+Return type: `Union[str, None]`
 
 ### Parameters
 
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
-| `value` | `str | None` | normal | -- | The value. |
+| `value` | `Union[str, None]` | normal | -- | The value. |
 
 
 
@@ -295,10 +287,10 @@ 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: str | None
+:type value: Union[str, None]
 
 :return: The value or ``None``.
-:rtype: str | None
+:rtype: Union[str, None]
 
 ## Function `get_relative_path_segments`
 
@@ -341,103 +333,3 @@ Returns the path segments relative to ``root``.
 
 :return: The path segments relative to ``root``.
 :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

licenses/docstring-parser.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Marcin Kurczewski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

licenses/iniconfig.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2010 - 2023 Holger Krekel and others
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

licenses/packaging.txt

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

licenses/pluggy.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 holger krekel (rather uses bitbucket/hpk42)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

licenses/pygments.txt

@@ -0,0 +1,25 @@
+Copyright (c) 2006-2022 by the respective authors (see AUTHORS file).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

licenses/pytest-expectdir.txt

@@ -0,0 +1,19 @@
+This is the MIT license: http://www.opensource.org/licenses/mit-license.php
+
+Copyright (c) 2015-2022 the pytest-datadir authors and contributors <see AUTHORS file>.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
+to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

licenses/pytest.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2004 Holger Krekel and others
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

poetry.lock

@@ -1,4 +1,4 @@
-# This file is automatically @generated by Poetry 2.5.1 and should not be changed by hand.
+# This file is automatically @generated by Poetry 2.4.3 and should not be changed by hand.
 
 [[package]]
 name = "colorama"
@@ -235,14 +235,14 @@ version = "4.16.0"
 description = "Backported and Experimental Type Hints for Python 3.9+"
 optional = false
 python-versions = ">=3.9"
-groups = ["main", "dev"]
+groups = ["dev"]
+markers = "python_version == \"3.10\""
 files = [
     {file = "typing_extensions-4.16.0-py3-none-any.whl", hash = "sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8"},
     {file = "typing_extensions-4.16.0.tar.gz", hash = "sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5"},
 ]
-markers = {dev = "python_version == \"3.10\""}
 
 [metadata]
 lock-version = "2.1"
 python-versions = ">=3.10"
-content-hash = "0fb3b53540e7a7fe173bf29a2031bd59f863a8dea94a29d51933de2375c3bfa2"
+content-hash = "24c9a2d464f6c737eeae0a66f792fa23824c3960b7cc72a22fff1408f21ec812"

pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "jcloud-docsgen"
-version = "0.2.3"
+version = "0.1.0"
 description = "A tool that generates Markdown documentation for software project source code"
-dependencies = ["docstring-parser", "typing-extensions (>=4.16.0,<5.0.0)"]
+dependencies = ["docstring-parser"]
 requires-python = ">=3.10"
 license = "Apache-2.0"
 

src/jcloud_docsgen/__init__.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 from . import cli
-from .core import *  # noqa: F403
+from .core import *
 from .core import __all__ as _core__all__
 
 __all__ = [

src/jcloud_docsgen/cli/cli.py

@@ -20,7 +20,6 @@ import argparse
 import pathlib
 import sys
 
-from ..exceptions import DirectoryNotEmptyError
 from .languages.python import VALID_SECTIONS as VALID_PYTHON_SECTIONS
 
 __all__ = [
@@ -82,15 +81,6 @@ def create_argument_parser() -> argparse.ArgumentParser:
         default='docs/reference',
         help='the output directory the documentation will be written to',
     )
-    common_parser.add_argument(
-        '-f',
-        '--force',
-        action='store_true',
-        help=(
-            'generate documentation even if the output directory is not '
-            'empty. Warning: data can be lost when setting this flag.'
-        ),
-    )
 
     argument_parser = argparse.ArgumentParser()
 
@@ -160,7 +150,6 @@ def main(argv=None) -> int:
                 exclude_sections=args.sections_exclude,
                 allow_html=args.allow_html,
                 allow_tables=args.allow_tables,
-                force=args.force,
             )
     except FileNotFoundError as exc:
         return error(f'{exc.filename}: no such file or directory')
@@ -168,8 +157,6 @@ def main(argv=None) -> int:
         return error(f'{exc.filename}: not a directory')
     except IsADirectoryError as exc:
         return error(f'{exc.filename}: is a directory')
-    except DirectoryNotEmptyError as exc:
-        return error(f'{exc.filename}: directory not empty')
     except FileExistsError as exc:
         return error(f'{exc.filename}: file already exists')
     except PermissionError as exc:

src/jcloud_docsgen/cli/languages/python.py

@@ -78,7 +78,6 @@ def _generate(
     ),
     allow_html: bool = False,
     allow_tables: bool = False,
-    force: bool = False,
 ) -> None:
     """
     Generates the documentation for a Python project.
@@ -95,9 +94,6 @@ def _generate(
     :type allow_html: bool
     :param allow_tables: Indicates whether Markdown tables are allowed.
                          Warning: Markdown tables are not CommonMark.
-    :param force: Indicates whether the output directory shall be
-                  overwritten if it is not empty.
-    :type force: bool
     """
 
     docs_generator = PythonDocumentationGenerator(
@@ -107,7 +103,7 @@ def _generate(
         allow_html=allow_html,
         allow_tables=allow_tables,
     )
-    docs_generator.generate_documentation(force)
+    docs_generator.generate_documentation()
 
 
 def generate(
@@ -118,7 +114,6 @@ def generate(
     exclude_sections: list[str] = [],
     allow_html: bool = False,
     allow_tables: bool = False,
-    force: bool = False,
 ) -> None:
     """
     Generates the documentation for a Python project.
@@ -138,9 +133,6 @@ def generate(
     :type allow_html: bool
     :param allow_tables: Indicates whether Markdown tables are allowed.
                          Warning: Markdown tables are not CommonMark.
-    :param force: Indicates whether the output directory shall be
-                  overwritten if it is not empty.
-    :type force: bool
     """
 
     sections = parse_sections_list(include_sections, exclude_sections)
@@ -151,5 +143,4 @@ def generate(
         include_sections=sections,
         allow_html=allow_html,
         allow_tables=allow_tables,
-        force=force,
     )

src/jcloud_docsgen/core/python/__init__.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 from . import namespaces
-from ._core import *  # noqa: F403
+from ._core import *
 from ._core import __all__ as _core__all__
 
 __all__ = [

src/jcloud_docsgen/core/python/_core.py

@@ -16,19 +16,14 @@ from __future__ import annotations
 
 import ast
 import pathlib
-import shutil
 from collections.abc import Iterator
 from dataclasses import dataclass
 from typing import TypeAlias
 
 import docstring_parser
 
-from ...exceptions import (
-    DirectoryNotEmptyError,
-    InvalidNamespaceError,
-    PythonArgumentStructureError,
-)
-from ...utils import get_relative_path_segments, markdown_table, non_empty_str
+from ...exceptions import InvalidNamespaceError, PythonArgumentStructureError
+from ...utils import get_relative_path_segments, non_empty_str
 from .arguments import PythonArgumentKind, PythonFunctionArgument
 from .definitions import (
     PythonAsyncFunctionDefinition,
@@ -37,11 +32,7 @@ from .definitions import (
     PythonFunctionDefinition,
 )
 from .docstrings import PythonDocstring
-from .namespaces import (
-    PythonModuleNamespace,
-    PythonPackageNamespace,
-    validate_namespace_name,
-)
+from .namespaces import PythonModuleNamespace, PythonPackageNamespace
 
 __all__ = [
     'PythonDefinitionDocumentationIncludeSections',
@@ -184,6 +175,130 @@ def _signature_argument_list(
     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: str | PythonDocstring | None) -> bool:
     """
     Checks whether the docstring is a docstring or an empty docstring.
@@ -481,10 +596,11 @@ class PythonDefinitionDocumentationGenerator:
 
         if _is_docstring(self.definition.doc) or not self.skip_empty_sections:
             if self.allow_html:
-                md += (
-                    f'<details><summary><h{str(self.level + 1)} style="displa'
-                    f'y:inline">Docstring</h{str(self.level + 1)}></summary>'
-                )
+                md += f'<details><summary><h{
+                    str(self.level + 1)
+                } style="display:inline">Docstring</h{
+                    str(self.level + 1)
+                }></summary>'
             else:
                 md += self.level * '#' + '# Docstring\n\n'
 
@@ -519,7 +635,7 @@ class PythonDefinitionDocumentationGenerator:
         )
 
         if params_types:
-            md += markdown_table(
+            md += _markdown_table(
                 ['Parameter', 'Type', 'Kind', 'Default value', 'Description'],
                 [
                     (
@@ -598,7 +714,7 @@ class PythonDefinitionDocumentationGenerator:
             md += self.level * '#' + '# Exceptions\n\n'
 
         if self._docstring.raises:
-            md += markdown_table(
+            md += _markdown_table(
                 ('Exception', 'Description'),
                 [
                     (
@@ -808,12 +924,9 @@ class PythonModuleDocumentationGenerator:
         ),
         **kwargs,
     ) -> None:
-        if not (
-            module_path.suffix == '.py'
-            and validate_namespace_name(module_path.stem)
-        ):
+        if module_path.name.count('.') > 1:
             raise InvalidNamespaceError(
-                'invalid module file name',
+                'namespace identifier cannot contain more than one dot',
                 namespace_identifier=module_path.name,
             )
 
@@ -981,29 +1094,13 @@ class PythonDocumentationGenerator:
         self.kwargs = kwargs
 
     def _namespace(self, directory: pathlib.Path) -> PythonPackageNamespace:
-        namespace = PythonPackageNamespace(
-            # fallback for the case that the path it '/'. In this case, the
-            # name would be ''. The fallback value is irrelevant; the name is
-            # only specified because PythonPackageNamespace requires
-            # specifying it. The name will not be included in the generated
-            # output.
-            directory.resolve().name or 'project',
-            [],
-        )
+        namespace = PythonPackageNamespace(directory.name, [])
 
         for entry in directory.iterdir():
-            try:
-                if entry.is_dir() and (
-                    entry.parent / (f'{entry.stem}.py')
-                ).resolve() not in [
-                    e.resolve() for e in entry.parent.iterdir()
-                ]:
+            if entry.is_dir():
                 namespace.add(self._namespace(entry))
             elif entry.suffix == '.py':
                 namespace.add(PythonModuleNamespace(entry.stem))
-            except InvalidNamespaceError:
-                # the name of the directory or module is invalid; ignore.
-                pass
 
         return namespace
 
@@ -1017,29 +1114,12 @@ class PythonDocumentationGenerator:
 
         return self._namespace(self.project_directory)
 
-    def generate_documentation(self, force: bool = False) -> None:
+    def generate_documentation(self) -> None:
         """
         Generates the full project documentation and writes it to the
         documentation directory.
-
-        :param force: Indicates whether existing contents of the output
-                      directory shall be overwritten. If ``True``, all
-                      contents of the output directory will be deleted
-                      first.
-        :type force: bool
-
-        :raises DirectoryNotEmptyError: If ``force`` is ``False`` and
-                                        the output directory is not
-                                        empty.
         """
 
-        if self.docs_directory.exists() and list(
-            self.docs_directory.iterdir()
-        ):
-            if force:
-                shutil.rmtree(self.docs_directory)
-            else:
-                raise DirectoryNotEmptyError(str(self.docs_directory))
         self.docs_directory.mkdir(parents=True, exist_ok=True)
 
         _generate_package_namespace_documentation(

src/jcloud_docsgen/core/python/namespaces.py

@@ -14,7 +14,6 @@
 
 from __future__ import annotations
 
-import keyword
 from typing import TypeAlias, Union
 
 from ...exceptions import (
@@ -25,47 +24,27 @@ from ...exceptions import (
 from ...utils import assert_that_is_instance
 
 __all__ = [
-    'validate_namespace_name',
     'PythonNamespace',
     'PythonPackageNamespace',
     'PythonModuleNamespace',
 ]
 
 
-def validate_namespace_name(name: str) -> bool:
-    """
-    Checks whether a namespace name is valid. Namespace names are valid
-    if they contain no dots and are valid Python identifiers.
-
-    :param name: The namespace name to validate.
-    :type name: str
-
-    :returns: Whether the namespace name is valid.
-    :rtype: bool
-    """
-
-    if not isinstance(name, str):
-        return False
-
-    return name.isidentifier() and not keyword.iskeyword(name)
-
-
 class PythonNamespace:
     """
     The base class for all Python namespaces such as modules or packages.
 
     :param name: The name of the namespace.
     :type name: str
-
-    :raises InvalidNamespaceError: If the namespace  name is invalid.
     """
 
     def __init__(self, name: str) -> None:
         assert_that_is_instance(name, str)
 
-        if not validate_namespace_name(name):
+        if not name.strip():
             raise InvalidNamespaceError(
-                'invalid namespace', namespace_identifier=name
+                'invalid namespace',
+                namespace_identifier=name,
             )
 
         self.name = name
@@ -91,8 +70,6 @@ class PythonPackageNamespace(PythonNamespace):
     :type name: str
     :param sub_namespaces: The sub-namespaces.
     :type sub_namespaces: list[PythonNamespace]
-
-    :raises InvalidNamespaceError: If the namespace name is invalid.
     """
 
     def __init__(
@@ -179,7 +156,7 @@ class PythonPackageNamespace(PythonNamespace):
         # For performance reasons, is not called self.sub_namespace_names
         # if the name attribute does not match, which can be quickly
         # verified
-        if not (isinstance(value, type(self)) and self.name == value.name):
+        if self.name != value.name:
             return False
 
         return value.sub_namespace_names() == self.sub_namespace_names()
@@ -246,4 +223,4 @@ class PythonModuleNamespace(PythonNamespace):
         super().__init__(name)
 
     def __eq__(self, value: PythonModuleNamespace) -> bool:
-        return isinstance(value, type(self)) and self.name == value.name
+        return self.name == value.name

src/jcloud_docsgen/exceptions.py

@@ -12,22 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import errno
-
-__all__ = [
-    'NamespaceError',
-    'InvalidNamespaceError',
-    'NamespaceNotFoundError',
-    'NamespaceExistsError',
-    'PythonIdentifierError',
-    'InvalidPythonIdentifierError',
-    'PythonAnnotationError',
-    'InvalidPythonAnnotationError',
-    'PythonDefinitionError',
-    'PythonArgumentStructureError',
-    'DirectoryNotEmptyError',
-]
-
 
 class NamespaceError(ValueError):
     """
@@ -42,11 +26,9 @@ class NamespaceError(ValueError):
         if not self.args:
             return ''
         else:
-            return (
-                self.args[0]
-                + (': ' if self.namespace_identifier and self.args[0] else '')
-                + (self.namespace_identifier if self.args[0] else '')
-            )
+            return f'{self.args[0]}{
+                ": " if self.namespace_identifier and self.args[0] else ""
+            }{self.namespace_identifier if self.args[0] else ""}'
 
 
 class InvalidNamespaceError(NamespaceError): ...
@@ -71,11 +53,9 @@ class PythonIdentifierError(ValueError):
         if not self.args:
             return ''
         else:
-            return (
-                self.args[0]
-                + (': ' if self.identifier and self.args[0] else '')
-                + (self.identifier if self.args[0] else '')
-            )
+            return f'{self.args[0]}{
+                ": " if self.identifier and self.args[0] else ""
+            }{self.identifier if self.args[0] else ""}'
 
 
 class InvalidPythonIdentifierError(PythonIdentifierError): ...
@@ -94,11 +74,9 @@ class PythonAnnotationError(ValueError):
         if not self.args:
             return ''
         else:
-            return (
-                self.args[0]
-                + (': ' if self.annotation and self.args[0] else '')
-                + (self.annotation if self.args[0] else '')
-            )
+            return f'{self.args[0]}{
+                ": " if self.annotation and self.args[0] else ""
+            }{self.annotation if self.args[0] else ""}'
 
 
 class InvalidPythonAnnotationError(PythonAnnotationError): ...
@@ -117,20 +95,9 @@ class PythonDefinitionError(ValueError):
         if not self.args:
             return ''
         else:
-            return (
-                self.args[0]
-                + (': ' if self.definition and self.args[0] else '')
-                + (self.definition if self.args[0] else '')
-            )
+            return f'{self.args[0]}{
+                ": " if self.definition and self.args[0] else ""
+            }{self.definition if self.args[0] else ""}'
 
 
 class PythonArgumentStructureError(PythonDefinitionError): ...
-
-
-class DirectoryNotEmptyError(OSError):
-    """
-    Directory is not empty.
-    """
-
-    def __init__(self, filename: str | None = None) -> None:
-        super().__init__(errno.ENOTEMPTY, 'Directory not empty', filename)

src/jcloud_docsgen/utils.py

@@ -20,6 +20,7 @@ import errno
 import os
 import pathlib
 import types
+from typing import Union
 
 try:
     from warnings import deprecated
@@ -27,18 +28,6 @@ except ImportError:
     from typing_extensions import deprecated
 
 
-__all__ = [
-    'ExistingDirectory',
-    'ExistingFile',
-    'human_readable_list',
-    'assert_that_is_instance',
-    'non_empty_str',
-    'get_relative_path_segments',
-    'fit_row_length',
-    'markdown_table',
-]
-
-
 @deprecated('Use pathlib.Path instead.')
 class ExistingDirectory(pathlib.Path):
     """
@@ -165,10 +154,10 @@ def assert_that_is_instance(
     obj: object,
     class_or_tuple: type | types.UnionType | tuple[type, ...],
 ) -> None:
-    if not isinstance(class_or_tuple, (type, types.UnionType, tuple)):
+    if not isinstance(class_or_tuple, Union[type, types.UnionType, tuple]):
         raise TypeError(
-            f"class_or_tuple: expected 'type | types.UnionType, tupl"
-            f"e[type, ...]', 'got {type(class_or_tuple).__name__}'",
+            f"class_or_tuple: expected 'Union[type, types.UnionType, "
+            f"tuple[type, ...]]', 'got {type(class_or_tuple).__name__}'",
         )
     if not isinstance(obj, class_or_tuple):
         if isinstance(class_or_tuple, (tuple, types.UnionType)):
@@ -186,8 +175,9 @@ def assert_that_is_instance(
         else:
             exception_message_expected = "'" + class_or_tuple.__name__ + "'"
         raise TypeError(
-            f'expected {exception_message_expected}'
-            f", got '{type(obj).__name__}'"
+            f"expected {exception_message_expected}, got '{
+                type(obj).__name__
+            }'",
         )
 
 
@@ -239,127 +229,3 @@ def get_relative_path_segments(
         )
         .parts,
     )
-
-
-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'
-                        f'{"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', ' ')
-                        .replace('|', '\\|')
-                        if one_line_values
-                        else str(
-                            col if col is not None else missing_value
-                        ).replace('|', '\\|')
-                        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'
-                        f'{"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()

tests/unit/cli/test_python.py

@@ -13,7 +13,6 @@
 # limitations under the License.
 
 import pathlib
-import tempfile
 
 import pytest
 
@@ -175,30 +174,7 @@ def test_sections_success():
 def test_docs_generation(expectdir):
     with expectdir('python_project') as output_dir:
         output_dir: pathlib.Path
-        (output_dir / 'test_dir').mkdir()
         input_dir = pathlib.Path(__file__).parent / 'python_project/project'
-        assert (
-            cli_main(
-                [
-                    'python',
-                    '-s',
-                    'params',
-                    'docstring',
-                    '-HTfo',
-                    str(output_dir),
-                    str(input_dir),
-                ]
-            )
-            == 0
-        )
-
-
-def test_docs_generation_error():
-    with tempfile.TemporaryDirectory() as output_dir:
-        output_dir = pathlib.Path(output_dir)
-        (output_dir / 'test_dir').mkdir()
-        input_dir = pathlib.Path(__file__).parent / 'python_project/project'
-        assert (
         cli_main(
             [
                 'python',
@@ -210,5 +186,3 @@ def test_docs_generation_error():
                 str(input_dir),
             ]
         )
-            == 1
-        )

tests/unit/core/python/_core/test_PythonDocumentationGenerator.py

@@ -13,16 +13,16 @@
 # limitations under the License.
 
 import pathlib
-import tempfile
 
 import pytest
 
+import tempfile
+
 from src.jcloud_docsgen.core.python import PythonDocumentationGenerator
 from src.jcloud_docsgen.core.python.namespaces import (
     PythonModuleNamespace,
     PythonPackageNamespace,
 )
-from src.jcloud_docsgen.exceptions import DirectoryNotEmptyError
 
 
 @pytest.mark.parametrize(
@@ -85,9 +85,7 @@ def test_PythonDocumentationGenerator_collect_modules(
     python_documentation_generator: PythonDocumentationGenerator,
     expected,
 ):
-    assert (
-        python_documentation_generator.namespace().sub_namespaces
-    ) == expected
+    assert python_documentation_generator.namespace().sub_namespaces == expected
 
 
 @pytest.mark.parametrize(
@@ -122,7 +120,7 @@ def test_generate_documentation(dir, expectdir):
             pathlib.Path(str(d)),
             allow_tables=True,
             allow_html=False,
-        ).generate_documentation(True)  # simplify the tests
+        ).generate_documentation()  # simplify the tests
 
 
 def test_creates_directory():
@@ -146,51 +144,3 @@ def test_creates_directory():
             )
             docs_generator.generate_documentation()
             assert docs_dir.exists()
-
-
-class TestForce:
-    def _prepare(self, directory):
-        directory = pathlib.Path(directory)
-        src_directory = directory / 'src'
-        src_directory.mkdir()
-        docs_directory = directory / 'docs'
-        docs_directory.mkdir()
-        return directory, src_directory, docs_directory
-
-    def test_overwrites_output_directory(self):
-        with tempfile.TemporaryDirectory() as directory:
-            directory, src_directory, docs_directory = self._prepare(directory)
-            test_dir = docs_directory / 'test_dir'
-            test_dir.mkdir()
-            documentation_generator = PythonDocumentationGenerator(
-                src_directory, docs_directory
-            )
-            documentation_generator.generate_documentation(True)
-            assert not test_dir.exists()
-
-    def test_error(self):
-        with tempfile.TemporaryDirectory() as directory:
-            directory, src_directory, docs_directory = self._prepare(directory)
-            (docs_directory / 'test_dir').mkdir()
-            documentation_generator = PythonDocumentationGenerator(
-                src_directory, docs_directory
-            )
-            with pytest.raises(DirectoryNotEmptyError) as exc_info:
-                documentation_generator.generate_documentation()
-            assert exc_info.value.filename == str(docs_directory)
-
-    def test_nothing_force(self):
-        with tempfile.TemporaryDirectory() as directory:
-            directory, src_directory, docs_directory = self._prepare(directory)
-            documentation_generator = PythonDocumentationGenerator(
-                src_directory, docs_directory
-            )
-            documentation_generator.generate_documentation(True)
-
-    def test_nothing_not_force(self):
-        with tempfile.TemporaryDirectory() as directory:
-            directory, src_directory, docs_directory = self._prepare(directory)
-            documentation_generator = PythonDocumentationGenerator(
-                src_directory, docs_directory
-            )
-            documentation_generator.generate_documentation(True)

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/expected/pkg/a/b.md

@@ -1,9 +0,0 @@
-# Module `pkg.a.b`
-
-## Function `fn`
-
-### Function signature
-
-```python
-fn()
-```

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/a-b/c-d.py

@@ -1 +0,0 @@
-def fn(): ...

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/a-b/c.d.py

@@ -1 +0,0 @@
-def fn(): ...

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/a-b/c.py

@@ -1 +0,0 @@
-def fn(): ...

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/a.b/c-d.py

@@ -1 +0,0 @@
-def fn(): ...

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/a.b/c.d.py

@@ -1 +0,0 @@
-def fn(): ...

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/a.b/c.py

@@ -1 +0,0 @@
-def fn(): ...

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/a/b-c.py

@@ -1 +0,0 @@
-def fn(): ...

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/a/b.c.py

@@ -1 +0,0 @@
-def fn(): ...

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/a/b.py

@@ -1 +0,0 @@
-def fn(): ...

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/c-d.py

@@ -1 +0,0 @@
-def fn(): ...

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/c.d.py

@@ -1 +0,0 @@
-def fn(): ...

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/module/module2.py

@@ -1,3 +0,0 @@
-"""
-Module 2.
-"""

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/expected/user_management/service.md

@@ -47,7 +47,7 @@ Return type: `User`
 | `user_id` | `str` | normal | -- | -- |
 | `name` | `str` | normal | -- | -- |
 | `email` | `str` | normal | -- | -- |
-| `age` | `int \| None` | normal | `None` | -- |
+| `age` | `int | None` | normal | `None` | -- |
 
 
 

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/expected/user_management/storage.md

@@ -125,12 +125,12 @@ Returns all users.
 ##### Method signature
 
 ```python
-list_all(self) -> list[User]
+list_all(self) -> List[User]
 ```
 
 ##### Returns
 
-Return type: `list[User]`
+Return type: `List[User]`
 
 ##### Parameters
 

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/user_management/models.py

@@ -1,4 +1,5 @@
 from dataclasses import dataclass
+from typing import Optional
 
 
 @dataclass
@@ -10,4 +11,4 @@ class User:
     id: str
     name: str
     email: str
-    age: int | None = None
+    age: Optional[int] = None

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/user_management/service.py

@@ -1,6 +1,6 @@
-from .exceptions import InvalidEmailError, UserNotFoundError
 from .models import User
 from .storage import InMemoryUserStorage
+from .exceptions import UserNotFoundError, InvalidEmailError
 from .utils import is_valid_email, normalize_name
 
 

tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/user_management/storage.py

@@ -1,3 +1,4 @@
+from typing import Dict, List
 from .models import User
 
 
@@ -8,7 +9,7 @@ class InMemoryUserStorage:
     """
 
     def __init__(self):
-        self._users: dict[str, User] = {}
+        self._users: Dict[str, User] = {}
 
     def add(self, user: User) -> None:
         """Adds a user."""
@@ -22,6 +23,6 @@ class InMemoryUserStorage:
         """Deletes a user."""
         del self._users[user_id]
 
-    def list_all(self) -> list[User]:
+    def list_all(self) -> List[User]:
         """Returns all users."""
         return list(self._users.values())

tests/unit/core/python/_core/test_PythonModuleDocumentationGenerator.py

@@ -25,134 +25,176 @@ from src.jcloud_docsgen.exceptions import InvalidNamespaceError
     [
         (
             pathlib.Path(
-                ('tests/unit/core/python/_core/invalid_module_names/a.b.c'),
-            ),
-            None,
-            InvalidNamespaceError,
-            'invalid module file name: a.b.c',
-        ),
                 (
-            pathlib.Path(
-                ('tests/unit/core/python/_core/invalid_module_names/a.b.c.d'),
+                    'tests/unit/core/python/_core/fil'
+                    'es_with_more_than_one_dot/a.b.c'
+                ),
             ),
             None,
             InvalidNamespaceError,
-            'invalid module file name: a.b.c.d',
+            'namespace identifier cannot contain more than one dot: a.b.c',
         ),
         (
             pathlib.Path(
                 (
-                    'tests/unit/core/python/_core/i'
-                    'nvalid_module_names/a.b.c.d.e'
+                    'tests/unit/core/python/_core/file'
+                    's_with_more_than_one_dot/a.b.c.d'
                 ),
             ),
             None,
             InvalidNamespaceError,
-            'invalid module file name: a.b.c.d.e',
+            'namespace identifier cannot contain more than one dot: a.b.c.d',
         ),
         (
             pathlib.Path(
                 (
-                    'tests/unit/core/python/_core/in'
-                    'valid_module_names/a.b.c.d.e.f'
+                    'tests/unit/core/python/_core/files'
+                    '_with_more_than_one_dot/a.b.c.d.e'
                 ),
             ),
             None,
             InvalidNamespaceError,
-            'invalid module file name: a.b.c.d.e.f',
+            (
+                'namespace identifier cannot cont'
+                'ain more than one dot: a.b.c.d.e'
+            ),
         ),
         (
             pathlib.Path(
                 (
-                    'tests/unit/core/python/_core/inv'
-                    'alid_module_names/a.b.c.d.e.f.g'
+                    'tests/unit/core/python/_core/files_'
+                    'with_more_than_one_dot/a.b.c.d.e.f'
                 ),
             ),
             None,
             InvalidNamespaceError,
-            'invalid module file name: a.b.c.d.e.f.g',
+            (
+                'namespace identifier cannot conta'
+                'in more than one dot: a.b.c.d.e.f'
+            ),
         ),
         (
             pathlib.Path(
                 (
-                    'tests/unit/core/python/_core/inva'
-                    'lid_module_names/a.b.c.d.e.f.g.h'
+                    'tests/unit/core/python/_core/files_w'
+                    'ith_more_than_one_dot/a.b.c.d.e.f.g'
                 ),
             ),
             None,
             InvalidNamespaceError,
-            'invalid module file name: a.b.c.d.e.f.g.h',
+            (
+                'namespace identifier cannot contai'
+                'n more than one dot: a.b.c.d.e.f.g'
+            ),
         ),
         (
             pathlib.Path(
                 (
-                    'tests/unit/core/python/_core/inval'
-                    'id_module_names/a.b.c.d.e.f.g.h.py'
+                    'tests/unit/core/python/_core/files_wi'
+                    'th_more_than_one_dot/a.b.c.d.e.f.g.h'
                 ),
             ),
             None,
             InvalidNamespaceError,
-            'invalid module file name: a.b.c.d.e.f.g.h.py',
+            (
+                'namespace identifier cannot contain'
+                ' more than one dot: a.b.c.d.e.f.g.h'
+            ),
         ),
         (
             pathlib.Path(
                 (
-                    'tests/unit/core/python/_core/inva'
-                    'lid_module_names/a.b.c.d.e.f.g.py'
+                    'tests/unit/core/python/_core/files_wit'
+                    'h_more_than_one_dot/a.b.c.d.e.f.g.h.py'
                 ),
             ),
             None,
             InvalidNamespaceError,
-            'invalid module file name: a.b.c.d.e.f.g.py',
+            (
+                'namespace identifier cannot contain m'
+                'ore than one dot: a.b.c.d.e.f.g.h.py'
+            ),
         ),
         (
             pathlib.Path(
                 (
-                    'tests/unit/core/python/_core/in'
-                    'lid_module_names/a.b.c.d.e.f.py'
+                    'tests/unit/core/python/_core/files_wi'
+                    'th_more_than_one_dot/a.b.c.d.e.f.g.py'
                 ),
             ),
             None,
             InvalidNamespaceError,
-            'invalid module file name: a.b.c.d.e.f.py',
+            (
+                'namespace identifier cannot contain '
+                'more than one dot: a.b.c.d.e.f.g.py'
+            ),
         ),
         (
             pathlib.Path(
                 (
-                    'tests/unit/core/python/_core/in'
-                    'valid_module_names/a.b.c.d.e.py'
+                    'tests/unit/core/python/_core/files_w'
+                    'ith_more_than_one_dot/a.b.c.d.e.f.py'
                 ),
             ),
             None,
             InvalidNamespaceError,
-            'invalid module file name: a.b.c.d.e.py',
+            (
+                'namespace identifier cannot contain'
+                ' more than one dot: a.b.c.d.e.f.py'
+            ),
         ),
         (
             pathlib.Path(
                 (
-                    'tests/unit/core/python/_core/i'
-                    'nvalid_module_names/a.b.c.d.py'
+                    'tests/unit/core/python/_core/files_'
+                    'with_more_than_one_dot/a.b.c.d.e.py'
                 ),
             ),
             None,
             InvalidNamespaceError,
-            'invalid module file name: a.b.c.d.py',
+            (
+                'namespace identifier cannot contai'
+                'n more than one dot: a.b.c.d.e.py'
+            ),
         ),
         (
             pathlib.Path(
-                ('tests/unit/core/python/_core/invalid_module_names/a.b.c.py'),
+                (
+                    'tests/unit/core/python/_core/files'
+                    '_with_more_than_one_dot/a.b.c.d.py'
+                ),
             ),
             None,
             InvalidNamespaceError,
-            'invalid module file name: a.b.c.py',
+            (
+                'namespace identifier cannot conta'
+                'in more than one dot: a.b.c.d.py'
+            ),
         ),
         (
             pathlib.Path(
-                ('tests/unit/core/python/_core/invalid_module_names/a.b.py'),
+                (
+                    'tests/unit/core/python/_core/file'
+                    's_with_more_than_one_dot/a.b.c.py'
+                ),
             ),
             None,
             InvalidNamespaceError,
-            'invalid module file name: a.b.py',
+            (
+                'namespace identifier cannot cont'
+                'ain more than one dot: a.b.c.py'
+            ),
+        ),
+        (
+            pathlib.Path(
+                (
+                    'tests/unit/core/python/_core/fil'
+                    'es_with_more_than_one_dot/a.b.py'
+                ),
+            ),
+            None,
+            InvalidNamespaceError,
+            'namespace identifier cannot contain more than one dot: a.b.py',
         ),
         (
             pathlib.Path(
@@ -163,7 +205,7 @@ from src.jcloud_docsgen.exceptions import InvalidNamespaceError
             ),
             None,
             InvalidNamespaceError,
-            'invalid module file name: a.b.py',
+            'namespace identifier cannot contain more than one dot: a.b.py',
         ),
     ],
 )
@@ -250,8 +292,8 @@ Return type: `int | float`
 
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
-| `a` | `int \\| float` | normal | -- | The first number. |
-| `b` | `int \\| float` | normal | -- | The second number. |
+| `a` | `int | float` | normal | -- | The first number. |
+| `b` | `int | float` | normal | -- | The second number. |
 
 
 
@@ -461,8 +503,8 @@ Return type: `int | float`
 
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
-| `a` | `int \\| float` | normal | -- | The first number. |
-| `b` | `int \\| float` | normal | -- | The second number. |
+| `a` | `int | float` | normal | -- | The first number. |
+| `b` | `int | float` | normal | -- | The second number. |
 
 
 
@@ -672,8 +714,8 @@ Return type: `int | float`
 
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
-| `a` | `int \\| float` | normal | -- | The first number. |
-| `b` | `int \\| float` | normal | -- | The second number. |
+| `a` | `int | float` | normal | -- | The first number. |
+| `b` | `int | float` | normal | -- | The second number. |
 
 
 

tests/unit/core/python/_core/test__collect_definitions.py

@@ -292,25 +292,22 @@ def test_PythonDocumentationGenerator_collect_modules(
                     None,
                     [
                         (
-                            "pytest.mark.parametrize('python_documentatio"
-                            "n_generator,expected', [(PythonDocumentation"
-                            "Generator(pathlib.Path('tests/unit/core/pyth"
-                            "on/_core/test_project_dirs/pdir_1'), pathlib"
-                            ".Path('tests/unit/core/python/_core/test_pro"
-                            "ject_dirs/pdir_1/docs')), []), (PythonDocume"
-                            "ntationGenerator(pathlib.Path('tests/unit/co"
-                            "re/python/_core/test_project_dirs/pdir_2'), "
-                            "pathlib.Path('tests/unit/core/python/_core/t"
-                            "est_project_dirs/pdir_2/docs')), [PythonPack"
-                            "ageNamespace('pkg', [PythonModuleNamespace('"
-                            "module')])]), (PythonDocumentationGenerator("
-                            "pathlib.Path('tests/unit/core/python/_core/t"
-                            "est_project_dirs/pdir_3'), pathlib.Path('tes"
-                            'ts/unit/core/python/_core/test_project_dirs/'
-                            "pdir_3/docs')), [PythonPackageNamespace('pkg"
-                            "', [PythonModuleNamespace('module'), Python"
-                            "PackageNamespace('pkg', [PythonModuleNames"
-                            "pace('module2')])])])])"
+                            """pytest.mark.parametrize('python_documentation_gener"""
+                            """ator,expected', [(PythonDocumentationGenerator(path"""
+                            """lib.Path('tests/unit/core/python/_core/test_project"""
+                            """_dirs/pdir_1'), pathlib.Path('tests/unit/core/pytho"""
+                            """n/_core/test_project_dirs/pdir_1/docs')), []), (Pyt"""
+                            """honDocumentationGenerator(pathlib.Path('tests/unit/"""
+                            """core/python/_core/test_project_dirs/pdir_2'), pathl"""
+                            """ib.Path('tests/unit/core/python/_core/test_project_"""
+                            """dirs/pdir_2/docs')), [PythonPackageNamespace('pkg',"""
+                            """ [PythonModuleNamespace('module')])]), (PythonDocum"""
+                            """entationGenerator(pathlib.Path('tests/unit/core/pyt"""
+                            """hon/_core/test_project_dirs/pdir_3'), pathlib.Path("""
+                            """'tests/unit/core/python/_core/test_project_dirs/pdi"""
+                            """r_3/docs')), [PythonPackageNamespace('pkg', [Python"""
+                            """ModuleNamespace(\'module'), PythonPackageNamespace("""
+                            """\'pkg\', [PythonModuleNamespace(\'module2')])])])])"""
                         )
                     ],
                 ),

tests/unit/core/python/_core/test__fit_row_length.py

@@ -14,7 +14,7 @@
 
 import pytest
 
-from src.jcloud_docsgen.utils import fit_row_length
+from src.jcloud_docsgen.core.python._core import _fit_row_length
 
 
 @pytest.mark.parametrize(
@@ -37,8 +37,8 @@ from src.jcloud_docsgen.utils import fit_row_length
         (3, (1, 2, 3), (1, 2, 3)),
     ],
 )
-def test_fit_row_length(expected_length, row, expected):
-    assert fit_row_length(expected_length, row) == expected
+def test__fit_row_length(expected_length, row, expected):
+    assert _fit_row_length(expected_length, row) == expected
 
 
 @pytest.mark.parametrize(
@@ -60,7 +60,7 @@ def test_fit_row_length(expected_length, row, expected):
         (-42, ValueError),
     ],
 )
-def test_fit_row_length_exceptions(expected_length, row, expected_exception):
+def test__fit_row_length_exceptions(expected_length, row, expected_exception):
     with pytest.raises(expected_exception) as exc_info:
-        fit_row_length(expected_length, row)
+        _fit_row_length(expected_length, row)
     assert str(exc_info.value) == 'expected must be larger than or equal 0.'

tests/unit/core/python/_core/test__markdown_table.py

@@ -14,7 +14,7 @@
 
 import pytest
 
-from src.jcloud_docsgen.utils import markdown_table
+from src.jcloud_docsgen.core.python._core import _markdown_table
 
 
 @pytest.mark.parametrize(
@@ -138,72 +138,6 @@ from src.jcloud_docsgen.utils import markdown_table
             """| a |
 | --- |
 | line1\nline2 |""",
-        ),
-        (
-            ['a'],
-            [('line1\nline2 | 2',)],
-            True,
-            False,
-            False,
-            '--',
-            """| a |
-| --- |
-| line1\nline2 \\| 2 |""",
-        ),
-        (
-            ['a'],
-            [('line1\nline2 | 2',)],
-            True,
-            False,
-            True,
-            '--',
-            """| a |
-| --- |
-| line1 line2 \\| 2 |""",
-        ),
-        (
-            ['a'],
-            [('1 | 2',)],
-            True,
-            False,
-            True,
-            '--',
-            """| a |
-| --- |
-| 1 \\| 2 |""",
-        ),
-        (
-            ['a'],
-            [('1 |',)],
-            True,
-            False,
-            True,
-            '--',
-            """| a |
-| --- |
-| 1 \\| |""",
-        ),
-        (
-            ['a'],
-            [('|',)],
-            True,
-            False,
-            True,
-            '--',
-            """| a |
-| --- |
-| \\| |""",
-        ),
-        (
-            ['a'],
-            [('| 2',)],
-            True,
-            False,
-            True,
-            '--',
-            """| a |
-| --- |
-| \\| 2 |""",
         ),
         (
             [],
@@ -318,7 +252,7 @@ from src.jcloud_docsgen.utils import markdown_table
         ),
     ],
 )
-def test_markdown_table(
+def test__markdown_table(
     header,
     body,
     allow_markdown_table,
@@ -328,7 +262,7 @@ def test_markdown_table(
     expected,
 ):
     assert (
-        markdown_table(
+        _markdown_table(
             header,
             body,
             allow_markdown_table=allow_markdown_table,
@@ -468,7 +402,7 @@ def test_markdown_table(
         ),
     ],
 )
-def test_markdown_table_exceptions(
+def test__markdown_table_exceptions(
     header,
     body,
     allow_markdown_table,
@@ -479,7 +413,7 @@ def test_markdown_table_exceptions(
     expected_exception_msg,
 ):
     with pytest.raises(expected_exception) as exc_info:
-        markdown_table(
+        _markdown_table(
             header,
             body,
             allow_markdown_table=allow_markdown_table,

tests/unit/core/python/namespaces/test_PythonModuleNamespace.py

@@ -14,11 +14,7 @@
 
 import pytest
 
-from src.jcloud_docsgen.core.python.namespaces import (
-    PythonModuleNamespace,
-    PythonNamespace,
-    PythonPackageNamespace,
-)
+from src.jcloud_docsgen.core.python.namespaces import PythonModuleNamespace
 
 
 class StrSubclass(str): ...
@@ -28,6 +24,7 @@ class StrSubclass(str): ...
     'namespace,expected_name',
     [
         (PythonModuleNamespace('a'), 'a'),
+        (PythonModuleNamespace('1'), '1'),
         (PythonModuleNamespace(StrSubclass('a')), StrSubclass('a')),
     ],
 )
@@ -40,11 +37,11 @@ def test_PythonModuleNamespace_name_attribute(namespace, expected_name):
     [
         (PythonModuleNamespace('a'), PythonModuleNamespace('a'), True),
         (PythonModuleNamespace('b'), PythonModuleNamespace('b'), True),
+        (PythonModuleNamespace('1'), PythonModuleNamespace('1'), True),
+        (PythonModuleNamespace('42'), PythonModuleNamespace('42'), True),
         (PythonModuleNamespace('a'), PythonModuleNamespace('b'), False),
-        (PythonModuleNamespace('a'), 'a', False),
-        (PythonModuleNamespace('a'), 'b', False),
-        (PythonModuleNamespace('a'), PythonPackageNamespace('a', []), False),
-        (PythonModuleNamespace('a'), PythonNamespace('a'), False),
+        (PythonModuleNamespace('0'), PythonModuleNamespace('-0'), False),
+        (PythonModuleNamespace('1'), PythonModuleNamespace('a'), False),
     ],
 )
 def test_PythonModuleNamespace___eq__(namespace1, namespace2, expected):
@@ -56,6 +53,7 @@ def test_PythonModuleNamespace___eq__(namespace1, namespace2, expected):
     'namespace,expected',
     [
         (PythonModuleNamespace('a'), "PythonModuleNamespace('a')"),
+        (PythonModuleNamespace('1'), "PythonModuleNamespace('1')"),
         (
             PythonModuleNamespace(StrSubclass('a')),
             "PythonModuleNamespace('a')",

tests/unit/core/python/namespaces/test_PythonNamespace.py

@@ -24,6 +24,7 @@ class StrSubclass(str): ...
     'namespace,expected_name',
     [
         (PythonNamespace('a'), 'a'),
+        (PythonNamespace('1'), '1'),
         (PythonNamespace(StrSubclass('a')), StrSubclass('a')),
     ],
 )
@@ -35,6 +36,7 @@ def test_PythonNamespace_name_attribute(namespace, expected_name):
     'namespace,expected',
     [
         (PythonNamespace('a'), "PythonNamespace('a')"),
+        (PythonNamespace('1'), "PythonNamespace('1')"),
         (PythonNamespace(StrSubclass('a')), "PythonNamespace('a')"),
     ],
 )

tests/unit/core/python/namespaces/test_PythonPackageNamespace.py

@@ -16,7 +16,6 @@ import pytest
 
 from src.jcloud_docsgen.core.python.namespaces import (
     PythonModuleNamespace,
-    PythonNamespace,
     PythonPackageNamespace,
 )
 from src.jcloud_docsgen.exceptions import (
@@ -38,6 +37,13 @@ class StrSubclass(str): ...
             ),
             'a',
         ),
+        (
+            PythonPackageNamespace(
+                '1',
+                [],
+            ),
+            '1',
+        ),
         (
             PythonPackageNamespace(
                 StrSubclass('a'),
@@ -250,26 +256,6 @@ def test_PythonPackageNamespace_sub_namespace_names(namespace, expected):
             PythonPackageNamespace('b', []),
             False,
         ),
-        (
-            PythonPackageNamespace('a', []),
-            'a',
-            False,
-        ),
-        (
-            PythonPackageNamespace('a', []),
-            'b',
-            False,
-        ),
-        (
-            PythonPackageNamespace('a', []),
-            PythonModuleNamespace('a'),
-            False,
-        ),
-        (
-            PythonPackageNamespace('a', []),
-            PythonNamespace('a'),
-            False,
-        ),
     ],
 )
 def test_PythonPackageNamespace___eq__(namespace1, namespace2, expected):
@@ -284,6 +270,10 @@ def test_PythonPackageNamespace___eq__(namespace1, namespace2, expected):
             PythonPackageNamespace('a', []),
             "PythonPackageNamespace('a', [])",
         ),
+        (
+            PythonPackageNamespace('1', []),
+            "PythonPackageNamespace('1', [])",
+        ),
         (
             PythonPackageNamespace(StrSubclass('a'), []),
             "PythonPackageNamespace('a', [])",

tests/unit/core/python/namespaces/test_validate_namespace_name.py

@@ -1,52 +0,0 @@
-# Copyright 2026 jCloud
-
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-
-#     http://www.apache.org/licenses/LICENSE-2.0
-
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-import pytest
-
-from src.jcloud_docsgen.core.python.namespaces import validate_namespace_name
-
-
-@pytest.mark.parametrize(
-    'name,expected',
-    [
-        ('a', True),
-        ('namespace', True),
-        ('match', True),
-        ('case', True),
-        ('type', True),
-        ('_', True),
-        ('__', True),
-        ('___', True),
-        ('_a', True),
-        ('_a_', True),
-        ('_a.', False),
-        ('a.b', False),
-        ('a-b', False),
-        ('a.', False),
-        ('a-', False),
-        ('.a', False),
-        ('-a', False),
-        ('.a.', False),
-        ('-a-', False),
-        ('.', False),
-        ('a-.b', False),
-        ('"', False),
-        ('""', False),
-        ('def', False),
-        ('class', False),
-        ('import', False),
-    ],
-)
-def test_validate_namespace_name(name, expected):
-    assert validate_namespace_name(name) == expected