Merge pull request 'Chore: prepare 0.2.3' (#75) from chore/prepare-0-2-3 into main

Reviewed-on: #75

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

@@ -0,0 +1,57 @@
+# 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.
+
+name: Generate API reference
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  generate:
+    runs-on: python
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      
+      - name: Install jcloud-docsgen
+        run: |
+          pip install \
+            --index-url https://gitea.jcloud-services.ddns.net/api/packages/jCloud/pypi/simple/ \
+            --extra-index-url https://pypi.org/simple \
+            jcloud-docsgen
+
+      - name: Generate documentation
+        run: |
+          jcloud-docsgen python -T -f -o docs/reference ./src
+
+      - name: Commit and push
+        run: |
+          git config user.name "${{ vars.BOT_NAME }}"
+          git config user.email "${{ vars.BOT_EMAIL }}"
+
+          git add docs/reference
+
+          if git diff --cached --quiet; then
+            echo "No changes"
+            exit 0
+          fi
+
+          git commit -m "chore: update API reference"
+          git push

.gitignore

@@ -1,5 +1,177 @@
-dist/
-src/*.egg-info/
-.vscode/
-.pytest_cache/
+# Byte-compiled / optimized / DLL files
 __pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# VS Code
+.vscode/

.gitmessage

@@ -0,0 +1,10 @@
+
+
+# ------------------------------------------------                       SUBJECT AREA
+# ---------------------------------------------------------------------- DETAIL AREA
+
+# Please enter a subject that does not exceed the limit of 50
+# characters.
+# If you enter a detailed description, no line should
+# exceed the limit of 72 characters. Break the line as soon as you
+# reach this limit.

NOTICE

@@ -1,41 +0,0 @@
-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.

README.md

@@ -7,11 +7,11 @@ Currently supported programming languages:
 
 ## Installation
 
-You can install it using pip:
+You can install the package `jcloud-docsgen` from the [Gitea Package Registry](https://gitea.jcloud-services.ddns.net/jCloud/-/packages/pypi/jcloud-docsgen/).
 
-```bash
-pip install jcloud-docsgen --index-url https://repo.jcloud-services.ddns.net/simple/ --extra-index-url https://pypi.org/simple/
-```
+## Setup
+
+Please execute `scripts/setup.sh` when cloning the repository to configure Git.
 
 ## Reference
 

docs/CHANGELOG.md

@@ -1,5 +1,49 @@
 # 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
+
+### 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
+
+### Deprecated
+
+- utility class for existing directories
+- utility class for existing files
+
 ## [0.1.0] - 2026-09-01
 
 ### Added

docs/reference/jcloud_docsgen/__init__.md

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

docs/reference/jcloud_docsgen/__main__.md

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

docs/reference/jcloud_docsgen/cli/__init__.md

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

docs/reference/jcloud_docsgen/cli/cli.md

@@ -0,0 +1,107 @@
+# 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

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

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

@@ -0,0 +1,156 @@
+# 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

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

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

@@ -0,0 +1 @@
+# 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]) -> tuple[list[PythonFunctionArgument], list[PythonFunctionArgument], Union[PythonFunctionArgument, None], list[PythonFunctionArgument], Union[PythonFunctionArgument, None]]
+_group_argument_list(argument_list: list[PythonFunctionArgument]) -> _Arguments
 ```
 
 ### Returns
 
-Return type: `tuple[list[PythonFunctionArgument], list[PythonFunctionArgument], Union[PythonFunctionArgument, None], list[PythonFunctionArgument], Union[PythonFunctionArgument, None]]`
+Return type: `_Arguments`
 
 ### 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: tuple[list[PythonFunctionArgument], list[PythonFunctionArgument], Union[PythonFunctionArgument, None], list[PythonFunctionArgument], Union[PythonFunctionArgument, None]]
+:rtype: _Arguments
 
 ## Function `_signature_argument_list`
 
@@ -116,106 +116,6 @@ 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.
@@ -224,7 +124,7 @@ Checks whether the docstring is a docstring or an empty docstring.
 ### Function signature
 
 ```python
-_is_docstring(docstring: Union[str, PythonDocstring, None]) -> bool
+_is_docstring(docstring: str | PythonDocstring | None) -> bool
 ```
 
 ### Returns
@@ -237,7 +137,7 @@ Return type: `bool`
 
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
-| `docstring` | `Union[str, PythonDocstring, None]` | normal | -- | The docstring. |
+| `docstring` | `str | PythonDocstring | None` | normal | -- | The docstring. |
 
 
 
@@ -250,7 +150,7 @@ Return type: `bool`
 Checks whether the docstring is a docstring or an empty docstring.
 
 :param docstring: The docstring.
-:type docstring: Union[str, PythonDocstring, None]
+:type docstring: str | PythonDocstring | None
 
 :return: Whether there is a docstring.
 :rtype: bool
@@ -975,7 +875,7 @@ A documentation generator for a Python module.
 ##### Method signature
 
 ```python
-__init__(self, module_path: ExistingFile, src_directory: Union[ExistingDirectory, None] = None, include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(), **kwargs) -> None
+__init__(self, module_path: pathlib.Path, src_directory: pathlib.Path | None = None, include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(), **kwargs) -> None
 ```
 
 ##### Returns
@@ -987,8 +887,8 @@ Return type: `None`
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
 | `self` | -- | normal | -- | -- |
-| `module_path` | `ExistingFile` | normal | -- | -- |
-| `src_directory` | `Union[ExistingDirectory, None]` | normal | `None` | -- |
+| `module_path` | `pathlib.Path` | normal | -- | -- |
+| `src_directory` | `pathlib.Path | None` | normal | `None` | -- |
 | `include_sections` | `PythonDefinitionDocumentationIncludeSections` | normal | `PythonDefinitionDocumentationIncludeSections()` | -- |
 | `kwargs` | -- | kwargs | -- | -- |
 
@@ -1125,11 +1025,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: ExistingFile
+:type module_path: pathlib.Path
 :param src_directory: The directory of the source code. It is
                       optional and only used for making the module
                       identifiers in the documentation relative.
-:type src_directory: Union[ExistingDirectory, None]
+:type src_directory: pathlib.Path | None
 :param include_sections: The sections that will be included.
 :type include_sections: PythonDefinitionDocumentationIncludeSections
 :param kwargs: The options for ``PythonDefinitionDocumentationGenerator``.
@@ -1197,7 +1097,7 @@ The class for the documentation generator.
 ##### Method signature
 
 ```python
-__init__(self, project_directory: ExistingDirectory, docs_directory: ExistingDirectory, include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(), **kwargs) -> None
+__init__(self, project_directory: pathlib.Path, docs_directory: pathlib.Path, include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(), **kwargs) -> None
 ```
 
 ##### Returns
@@ -1209,8 +1109,8 @@ Return type: `None`
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
 | `self` | -- | normal | -- | -- |
-| `project_directory` | `ExistingDirectory` | normal | -- | -- |
-| `docs_directory` | `ExistingDirectory` | normal | -- | -- |
+| `project_directory` | `pathlib.Path` | normal | -- | -- |
+| `docs_directory` | `pathlib.Path` | normal | -- | -- |
 | `include_sections` | `PythonDefinitionDocumentationIncludeSections` | normal | `PythonDefinitionDocumentationIncludeSections()` | -- |
 | `kwargs` | -- | kwargs | -- | -- |
 
@@ -1241,14 +1141,14 @@ Returns the project as a namespace.
 ##### Method signature
 
 ```python
-namespace(self) -> list[PythonPackageNamespace]
+namespace(self) -> PythonPackageNamespace
 ```
 
 ##### Returns
 
 The project as a namespace.
 
-Return type: `list[PythonPackageNamespace]`
+Return type: `PythonPackageNamespace`
 
 ##### Parameters
 
@@ -1267,7 +1167,7 @@ Return type: `list[PythonPackageNamespace]`
 Returns the project as a namespace.
 
 :return: The project as a namespace.
-:rtype: list[PythonPackageNamespace]
+:rtype: PythonPackageNamespace:
 
 #### Method `generate_documentation`
 
@@ -1277,7 +1177,7 @@ documentation directory.
 ##### Method signature
 
 ```python
-generate_documentation(self) -> None
+generate_documentation(self, force: bool = False) -> None
 ```
 
 ##### Returns
@@ -1289,8 +1189,13 @@ 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. |
 
 
 
@@ -1301,6 +1206,16 @@ 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.
+
 
 
 
@@ -1310,9 +1225,9 @@ documentation directory.
 The class for the documentation generator.
 
 :param project_directory: The directory of the project.
-:type project_directory: ExistingDirectory
+:type project_directory: pathlib.Path
 :param docs_directory: The directory for the generated documentation.
-:type docs_directory: ExistingDirectory
+:type docs_directory: pathlib.Path
 :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: Union[str, None], annotation: Union[str, None]) -> None
+__init__(self, name: str, kind: PythonArgumentKind, default: str | None, annotation: str | None) -> None
 ```
 
 ##### Returns
@@ -34,8 +34,8 @@ Return type: `None`
 | `self` | -- | normal | -- | -- |
 | `name` | `str` | normal | -- | -- |
 | `kind` | `PythonArgumentKind` | normal | -- | -- |
-| `default` | `Union[str, None]` | normal | -- | -- |
-| `annotation` | `Union[str, None]` | normal | -- | -- |
+| `default` | `str | None` | normal | -- | -- |
+| `annotation` | `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: Union[str, None]
+:type default: str | None
 :param annotation: The type annotation of the argument.
-:type annotation: Union[str, None]
+:type annotation: str | None
 
 ## Class `PythonASTArgumentsListParser`
 

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

@@ -8,20 +8,20 @@ not ``None``.
 ### Function signature
 
 ```python
-_python_docstring(doc: Union[str, None]) -> Union[PythonDocstring, None]
+_python_docstring(doc: str | None) -> PythonDocstring | None
 ```
 
 ### Returns
 
 The PythonDocstring object or ``None``.
 
-Return type: `Union[PythonDocstring, None]`
+Return type: `PythonDocstring | None`
 
 ### Parameters
 
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
-| `doc` | `Union[str, None]` | normal | -- | The docstring. |
+| `doc` | `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: Union[str, None]
+:type doc: str | None
 
 :return: The PythonDocstring object or ``None``.
-:rtype: Union[PythonDocstring, None]
+:rtype: PythonDocstring | None
 
 ## Class `PythonDefinition`
 
@@ -54,7 +54,7 @@ function definition) classes.
 ##### Method signature
 
 ```python
-__init__(self, name: str, doc: Union[PythonDocstring, None], decorators: list[str]) -> None
+__init__(self, name: str, doc: PythonDocstring | None, decorators: list[str]) -> None
 ```
 
 ##### Returns
@@ -67,7 +67,7 @@ Return type: `None`
 | --- | --- | --- | --- | --- |
 | `self` | -- | normal | -- | -- |
 | `name` | `str` | normal | -- | -- |
-| `doc` | `Union[PythonDocstring, None]` | normal | -- | -- |
+| `doc` | `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: Union[PythonDocstring, None]
+:type doc: 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: Union[str, None], doc: Union[PythonDocstring, None], decorators: list[str]) -> None
+__init__(self, name: str, args: list[PythonFunctionArgument], returns: str | None, doc: PythonDocstring | None, decorators: list[str]) -> None
 ```
 
 ##### Returns
@@ -213,8 +213,8 @@ Return type: `None`
 | `self` | -- | normal | -- | -- |
 | `name` | `str` | normal | -- | -- |
 | `args` | `list[PythonFunctionArgument]` | normal | -- | -- |
-| `returns` | `Union[str, None]` | normal | -- | -- |
-| `doc` | `Union[PythonDocstring, None]` | normal | -- | -- |
+| `returns` | `str | None` | normal | -- | -- |
+| `doc` | `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: Union[str, None]
+:type returns: str | None
 :param doc: The docstring.
-:type doc: Union[PythonDocstring, None]
+:type doc: 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: Union[str, None]
+:type returns: str | None
 :param doc: The docstring.
-:type doc: Union[PythonDocstring, None]
+:type doc: 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: Union[PythonDocstring, None], decorators: list[str], body: list[PythonDefinition]) -> None
+__init__(self, name: str, bases: list[str], doc: 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` | `Union[PythonDocstring, None]` | normal | -- | -- |
+| `doc` | `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: Union[PythonDocstring, None]
+:type doc: PythonDocstring | None
 :param decorators: The definition decorators.
 :type decorators: list[str]
 :param body:

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

@@ -1,5 +1,45 @@
 # 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.
@@ -57,6 +97,8 @@ 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.
@@ -73,7 +115,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
@@ -86,7 +128,7 @@ Return type: `None`
 | --- | --- | --- | --- | --- |
 | `self` | -- | normal | -- | -- |
 | `name` | `str` | normal | -- | -- |
-| `sub_namespaces` | `List[PythonNamespace]` | normal | -- | -- |
+| `sub_namespaces` | `list[PythonNamespace]` | normal | -- | -- |
 
 #### Method `namespace`
 
@@ -96,7 +138,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
@@ -110,7 +152,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
 
@@ -347,12 +389,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
 
@@ -381,6 +423,8 @@ 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

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

@@ -1,21 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,177 +0,0 @@
-
-                                 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

@@ -1,21 +0,0 @@
-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

@@ -1,25 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -0,0 +1,248 @@
+# This file is automatically @generated by Poetry 2.5.1 and should not be changed by hand.
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+description = "Cross-platform colored terminal text."
+optional = false
+python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7"
+groups = ["dev"]
+markers = "sys_platform == \"win32\""
+files = [
+    {file = "colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6"},
+    {file = "colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44"},
+]
+
+[[package]]
+name = "docstring-parser"
+version = "0.18.0"
+description = "Parse Python docstrings in reST, Google and Numpydoc format"
+optional = false
+python-versions = ">=3.8"
+groups = ["main"]
+files = [
+    {file = "docstring_parser-0.18.0-py3-none-any.whl", hash = "sha256:b3fcbed555c47d8479be0796ef7e19c2670d428d72e96da63f3a40122860374b"},
+    {file = "docstring_parser-0.18.0.tar.gz", hash = "sha256:292510982205c12b1248696f44959db3cdd1740237a968ea1e2e7a900eeb2015"},
+]
+
+[package.extras]
+dev = ["pre-commit (>=2.16.0) ; python_version >= \"3.9\"", "pydoctor (>=25.4.0)", "pytest"]
+docs = ["pydoctor (>=25.4.0)"]
+test = ["pytest"]
+
+[[package]]
+name = "exceptiongroup"
+version = "1.3.1"
+description = "Backport of PEP 654 (exception groups)"
+optional = false
+python-versions = ">=3.7"
+groups = ["dev"]
+markers = "python_version == \"3.10\""
+files = [
+    {file = "exceptiongroup-1.3.1-py3-none-any.whl", hash = "sha256:a7a39a3bd276781e98394987d3a5701d0c4edffb633bb7a5144577f82c773598"},
+    {file = "exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219"},
+]
+
+[package.dependencies]
+typing-extensions = {version = ">=4.6.0", markers = "python_version < \"3.13\""}
+
+[package.extras]
+test = ["pytest (>=6)"]
+
+[[package]]
+name = "iniconfig"
+version = "2.3.0"
+description = "brain-dead simple config-ini parsing"
+optional = false
+python-versions = ">=3.10"
+groups = ["dev"]
+files = [
+    {file = "iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12"},
+    {file = "iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730"},
+]
+
+[[package]]
+name = "packaging"
+version = "26.3"
+description = "Core utilities for Python packages"
+optional = false
+python-versions = ">=3.9"
+groups = ["dev"]
+files = [
+    {file = "packaging-26.3-py3-none-any.whl", hash = "sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c"},
+    {file = "packaging-26.3.tar.gz", hash = "sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79"},
+]
+
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+description = "plugin and hook calling mechanisms for python"
+optional = false
+python-versions = ">=3.9"
+groups = ["dev"]
+files = [
+    {file = "pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746"},
+    {file = "pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3"},
+]
+
+[package.extras]
+dev = ["pre-commit", "tox"]
+testing = ["coverage", "pytest", "pytest-benchmark"]
+
+[[package]]
+name = "pygments"
+version = "2.21.0"
+description = "Pygments is a syntax highlighting package written in Python."
+optional = false
+python-versions = ">=3.9"
+groups = ["dev"]
+files = [
+    {file = "pygments-2.21.0-py3-none-any.whl", hash = "sha256:2363c69b61c4a97c838da3b130dcd6468f4848992b21a82f2a63ec34377137d9"},
+    {file = "pygments-2.21.0.tar.gz", hash = "sha256:610ca751c9bc2492b38eb9a38a7fbc93edbbb2d7182edaf34e66ae493dee5c8c"},
+]
+
+[package.extras]
+windows-terminal = ["colorama (>=0.4.6)"]
+
+[[package]]
+name = "pytest"
+version = "9.1.1"
+description = "pytest: simple powerful testing with Python"
+optional = false
+python-versions = ">=3.10"
+groups = ["dev"]
+files = [
+    {file = "pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c"},
+    {file = "pytest-9.1.1.tar.gz", hash = "sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313"},
+]
+
+[package.dependencies]
+colorama = {version = ">=0.4", markers = "sys_platform == \"win32\""}
+exceptiongroup = {version = ">=1", markers = "python_version < \"3.11\""}
+iniconfig = ">=1.0.1"
+packaging = ">=22"
+pluggy = ">=1.5,<2"
+pygments = ">=2.7.2"
+tomli = {version = ">=1", markers = "python_version < \"3.11\""}
+
+[package.extras]
+dev = ["argcomplete", "attrs (>=19.2)", "hypothesis (>=3.56)", "mock", "requests", "setuptools", "xmlschema"]
+
+[[package]]
+name = "pytest-expectdir"
+version = "1.2.0"
+description = "A pytest plugin to provide initial/expected directories, and check a test transforms the initial directory to the expected one"
+optional = false
+python-versions = ">=3.7"
+groups = ["dev"]
+files = [
+    {file = "pytest-expectdir-1.2.0.tar.gz", hash = "sha256:145b7f86d4e8ae7c7cace3007f32d68afbdd4d18c392b3d5792794f8e9d51fae"},
+    {file = "pytest_expectdir-1.2.0-py3-none-any.whl", hash = "sha256:8fa19e7c0b69d6bfd0e81c6e33c9a8283eb14a7bab8408067e430a827a03f993"},
+]
+
+[package.dependencies]
+pytest = ">=5.0"
+
+[[package]]
+name = "ruff"
+version = "0.16.8"
+description = "An extremely fast Python linter and code formatter, written in Rust."
+optional = false
+python-versions = ">=3.7"
+groups = ["dev"]
+files = [
+    {file = "ruff-0.16.8-py3-none-linux_armv6l.whl", hash = "sha256:6ffbd6d87383c1edf5f6fa890f10200950240d7c1a16052a19a09d3a2307dd38"},
+    {file = "ruff-0.16.8-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:42ed6b878ed61e3acca92f2730a17acff39286944ea82398544696366a6f925e"},
+    {file = "ruff-0.16.8-py3-none-macosx_11_0_arm64.whl", hash = "sha256:7ea781c7f2afba8c6a505ea0fb3f994020249e0c450635f5381286fea6b46170"},
+    {file = "ruff-0.16.8-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8efeae3bbe414a5efefda11a792dfb51ef90ac48d50c4830de2f644caf3e8659"},
+    {file = "ruff-0.16.8-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:3a79b795469fef7fc6e908b218eed2eb17332afd85031db6480dc864560e69b2"},
+    {file = "ruff-0.16.8-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:3fdc5563cdc50555e6fba39322850860e9267c1b3d12c26a74729d8604c3c812"},
+    {file = "ruff-0.16.8-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:34508983c70665578dab88f5223d8e6228307e1135398ca8bfc8b7e9501e282b"},
+    {file = "ruff-0.16.8-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:644bb578569e0ffc575741232bd385dacdd6fbe123f1a729e7a225f54aa3957f"},
+    {file = "ruff-0.16.8-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:15e7d226246961db9235098333caa13063906d3851136b84c2900b82f5daa1df"},
+    {file = "ruff-0.16.8-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:a2bf6bc3e9ebdd4449abc6f06cf64b98051a2c61cf94d2fe9596518c881f1a1e"},
+    {file = "ruff-0.16.8-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:6ca111ba0849539165e9e59d2b442542f3c1e8060ebbdea82494f1ffbccb1e1f"},
+    {file = "ruff-0.16.8-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:359a1e5b495448ee1e91018064382ebc86f90e8aac2fed222c7d0e4e8df85fd2"},
+    {file = "ruff-0.16.8-py3-none-musllinux_1_2_i686.whl", hash = "sha256:59e8f5681349474110b24d62e93cfda6593f5fa3473446ca3705200cac1a08b9"},
+    {file = "ruff-0.16.8-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:efa3e7a16d1baaa79957888dfdf8be9ef2e44db81cb032af06d76632ab59e773"},
+    {file = "ruff-0.16.8-py3-none-win32.whl", hash = "sha256:55793ba85c69921e89be061426d91a78652d6e50317c962240922747a4eb713f"},
+    {file = "ruff-0.16.8-py3-none-win_amd64.whl", hash = "sha256:a6b85621fd3c81e31fc5f5add09c9c078b430db3595ca632efafdec9e64ebfaa"},
+    {file = "ruff-0.16.8-py3-none-win_arm64.whl", hash = "sha256:d075e820af612102ce217f07cc93e69f9490b10ec13ea85fa87bd03d996cef8a"},
+    {file = "ruff-0.16.8.tar.gz", hash = "sha256:9247bf92b5f04d825c8639a4fe423ec2e4222acd9222e58412b0dab7e442798b"},
+]
+
+[[package]]
+name = "tomli"
+version = "2.4.1"
+description = "A lil' TOML parser"
+optional = false
+python-versions = ">=3.8"
+groups = ["dev"]
+markers = "python_version == \"3.10\""
+files = [
+    {file = "tomli-2.4.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:f8f0fc26ec2cc2b965b7a3b87cd19c5c6b8c5e5f436b984e85f486d652285c30"},
+    {file = "tomli-2.4.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:4ab97e64ccda8756376892c53a72bd1f964e519c77236368527f758fbc36a53a"},
+    {file = "tomli-2.4.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:96481a5786729fd470164b47cdb3e0e58062a496f455ee41b4403be77cb5a076"},
+    {file = "tomli-2.4.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5a881ab208c0baf688221f8cecc5401bd291d67e38a1ac884d6736cbcd8247e9"},
+    {file = "tomli-2.4.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:47149d5bd38761ac8be13a84864bf0b7b70bc051806bc3669ab1cbc56216b23c"},
+    {file = "tomli-2.4.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:ec9bfaf3ad2df51ace80688143a6a4ebc09a248f6ff781a9945e51937008fcbc"},
+    {file = "tomli-2.4.1-cp311-cp311-win32.whl", hash = "sha256:ff2983983d34813c1aeb0fa89091e76c3a22889ee83ab27c5eeb45100560c049"},
+    {file = "tomli-2.4.1-cp311-cp311-win_amd64.whl", hash = "sha256:5ee18d9ebdb417e384b58fe414e8d6af9f4e7a0ae761519fb50f721de398dd4e"},
+    {file = "tomli-2.4.1-cp311-cp311-win_arm64.whl", hash = "sha256:c2541745709bad0264b7d4705ad453b76ccd191e64aa6f0fc66b69a293a45ece"},
+    {file = "tomli-2.4.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:c742f741d58a28940ce01d58f0ab2ea3ced8b12402f162f4d534dfe18ba1cd6a"},
+    {file = "tomli-2.4.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:7f86fd587c4ed9dd76f318225e7d9b29cfc5a9d43de44e5754db8d1128487085"},
+    {file = "tomli-2.4.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ff18e6a727ee0ab0388507b89d1bc6a22b138d1e2fa56d1ad494586d61d2eae9"},
+    {file = "tomli-2.4.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:136443dbd7e1dee43c68ac2694fde36b2849865fa258d39bf822c10e8068eac5"},
+    {file = "tomli-2.4.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:5e262d41726bc187e69af7825504c933b6794dc3fbd5945e41a79bb14c31f585"},
+    {file = "tomli-2.4.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:5cb41aa38891e073ee49d55fbc7839cfdb2bc0e600add13874d048c94aadddd1"},
+    {file = "tomli-2.4.1-cp312-cp312-win32.whl", hash = "sha256:da25dc3563bff5965356133435b757a795a17b17d01dbc0f42fb32447ddfd917"},
+    {file = "tomli-2.4.1-cp312-cp312-win_amd64.whl", hash = "sha256:52c8ef851d9a240f11a88c003eacb03c31fc1c9c4ec64a99a0f922b93874fda9"},
+    {file = "tomli-2.4.1-cp312-cp312-win_arm64.whl", hash = "sha256:f758f1b9299d059cc3f6546ae2af89670cb1c4d48ea29c3cacc4fe7de3058257"},
+    {file = "tomli-2.4.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:36d2bd2ad5fb9eaddba5226aa02c8ec3fa4f192631e347b3ed28186d43be6b54"},
+    {file = "tomli-2.4.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:eb0dc4e38e6a1fd579e5d50369aa2e10acfc9cace504579b2faabb478e76941a"},
+    {file = "tomli-2.4.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c7f2c7f2b9ca6bdeef8f0fa897f8e05085923eb091721675170254cbc5b02897"},
+    {file = "tomli-2.4.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f3c6818a1a86dd6dca7ddcaaf76947d5ba31aecc28cb1b67009a5877c9a64f3f"},
+    {file = "tomli-2.4.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d312ef37c91508b0ab2cee7da26ec0b3ed2f03ce12bd87a588d771ae15dcf82d"},
+    {file = "tomli-2.4.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:51529d40e3ca50046d7606fa99ce3956a617f9b36380da3b7f0dd3dd28e68cb5"},
+    {file = "tomli-2.4.1-cp313-cp313-win32.whl", hash = "sha256:2190f2e9dd7508d2a90ded5ed369255980a1bcdd58e52f7fe24b8162bf9fedbd"},
+    {file = "tomli-2.4.1-cp313-cp313-win_amd64.whl", hash = "sha256:8d65a2fbf9d2f8352685bc1364177ee3923d6baf5e7f43ea4959d7d8bc326a36"},
+    {file = "tomli-2.4.1-cp313-cp313-win_arm64.whl", hash = "sha256:4b605484e43cdc43f0954ddae319fb75f04cc10dd80d830540060ee7cd0243cd"},
+    {file = "tomli-2.4.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:fd0409a3653af6c147209d267a0e4243f0ae46b011aa978b1080359fddc9b6cf"},
+    {file = "tomli-2.4.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:a120733b01c45e9a0c34aeef92bf0cf1d56cfe81ed9d47d562f9ed591a9828ac"},
+    {file = "tomli-2.4.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:559db847dc486944896521f68d8190be1c9e719fced785720d2216fe7022b662"},
+    {file = "tomli-2.4.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:01f520d4f53ef97964a240a035ec2a869fe1a37dde002b57ebc4417a27ccd853"},
+    {file = "tomli-2.4.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7f94b27a62cfad8496c8d2513e1a222dd446f095fca8987fceef261225538a15"},
+    {file = "tomli-2.4.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:ede3e6487c5ef5d28634ba3f31f989030ad6af71edfb0055cbbd14189ff240ba"},
+    {file = "tomli-2.4.1-cp314-cp314-win32.whl", hash = "sha256:3d48a93ee1c9b79c04bb38772ee1b64dcf18ff43085896ea460ca8dec96f35f6"},
+    {file = "tomli-2.4.1-cp314-cp314-win_amd64.whl", hash = "sha256:88dceee75c2c63af144e456745e10101eb67361050196b0b6af5d717254dddf7"},
+    {file = "tomli-2.4.1-cp314-cp314-win_arm64.whl", hash = "sha256:b8c198f8c1805dc42708689ed6864951fd2494f924149d3e4bce7710f8eb5232"},
+    {file = "tomli-2.4.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:d4d8fe59808a54658fcc0160ecfb1b30f9089906c50b23bcb4c69eddc19ec2b4"},
+    {file = "tomli-2.4.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7008df2e7655c495dd12d2a4ad038ff878d4ca4b81fccaf82b714e07eae4402c"},
+    {file = "tomli-2.4.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1d8591993e228b0c930c4bb0db464bdad97b3289fb981255d6c9a41aedc84b2d"},
+    {file = "tomli-2.4.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:734e20b57ba95624ecf1841e72b53f6e186355e216e5412de414e3c51e5e3c41"},
+    {file = "tomli-2.4.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:8a650c2dbafa08d42e51ba0b62740dae4ecb9338eefa093aa5c78ceb546fcd5c"},
+    {file = "tomli-2.4.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:504aa796fe0569bb43171066009ead363de03675276d2d121ac1a4572397870f"},
+    {file = "tomli-2.4.1-cp314-cp314t-win32.whl", hash = "sha256:b1d22e6e9387bf4739fbe23bfa80e93f6b0373a7f1b96c6227c32bef95a4d7a8"},
+    {file = "tomli-2.4.1-cp314-cp314t-win_amd64.whl", hash = "sha256:2c1c351919aca02858f740c6d33adea0c5deea37f9ecca1cc1ef9e884a619d26"},
+    {file = "tomli-2.4.1-cp314-cp314t-win_arm64.whl", hash = "sha256:eab21f45c7f66c13f2a9e0e1535309cee140182a9cdae1e041d02e47291e8396"},
+    {file = "tomli-2.4.1-py3-none-any.whl", hash = "sha256:0d85819802132122da43cb86656f8d1f8c6587d54ae7dcaf30e90533028b49fe"},
+    {file = "tomli-2.4.1.tar.gz", hash = "sha256:7c7e1a961a0b2f2472c1ac5b69affa0ae1132c39adcb67aba98568702b9cc23f"},
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.16.0"
+description = "Backported and Experimental Type Hints for Python 3.9+"
+optional = false
+python-versions = ">=3.9"
+groups = ["main", "dev"]
+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"

pyproject.toml

@@ -1,16 +1,47 @@
 [build-system]
-requires = ["setuptools", "wheel"]
-build-backend = "setuptools.build_meta"
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "jcloud-docsgen"
-version = "0.1.0"
+version = "0.2.3"
 description = "A tool that generates Markdown documentation for software project source code"
-dependencies = ["docstring-parser"]
+dependencies = ["docstring-parser", "typing-extensions (>=4.16.0,<5.0.0)"]
+requires-python = ">=3.10"
 license = "Apache-2.0"
 
-[tool.setuptools]
-package-dir = {"" = "src"}
+[project.scripts]
+jcloud-docsgen = "jcloud_docsgen.cli:main"
 
-[tool.setuptools.packages.find]
-where = ["src"]
+[tool.poetry]
+packages = [
+    { include = "jcloud_docsgen", from = "src"}
+]
+
+[[tool.poetry.source]]
+name = "jcloud"
+url = "https://gitea.jcloud-services.ddns.net/api/packages/jCloud/pypi/simple/"
+priority = "supplemental"
+
+[dependency-groups]
+dev = [
+    "pytest (>=9.1.1,<10.0.0)",
+    "pytest-expectdir (>=1.2.0,<2.0.0)",
+    "ruff (>=0.16.8,<0.17.0)"
+]
+
+[tool.ruff]
+line-length = 79
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "UP"
+]
+
+[tool.ruff.format]
+quote-style = "single"

scripts/setup.sh

@@ -0,0 +1,15 @@
+# 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.
+
+git config --local commit.template .gitmessage

src/jcloud_docsgen/__init__.py

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

src/jcloud_docsgen/__main__.py

@@ -0,0 +1,20 @@
+# 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 sys
+
+from .cli.cli import main
+
+if __name__ == '__main__':
+    sys.exit(main())

src/jcloud_docsgen/cli.py

@@ -1,37 +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.
-
-'''
-The command line interface
-'''
-
-__all__ = [
-    'main'
-]
-
-import argparse
-import pathlib
-from .utils import ExistingDirectory
-
-def existing_directory(path: str, *args, **kwargs) -> pathlib.Path:
-    try:
-        return ExistingDirectory(path, *args, **kwargs)
-    except (FileNotFoundError, NotADirectoryError) as e:
-        raise argparse.ArgumentTypeError(f'{e.filename}{": " + e.args[1] if len(e.args) > 1 else ""}')
-
-def main() -> int:
-    argument_parser = argparse.ArgumentParser()
-    argument_parser.add_argument('project_directory', type = existing_directory, default = pathlib.Path('.'), help = 'The directory of the project')
-    args = argument_parser.parse_args()
-    return 0

src/jcloud_docsgen/cli/__init__.py

@@ -0,0 +1,22 @@
+# 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.
+
+from . import cli, languages
+from .cli import main
+
+__all__ = [
+    'cli',
+    'languages',
+    'main',
+]

src/jcloud_docsgen/cli/cli.py

@@ -0,0 +1,190 @@
+# 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.
+
+"""
+The command line interface
+"""
+
+import argparse
+import pathlib
+import sys
+
+from ..exceptions import DirectoryNotEmptyError
+from .languages.python import VALID_SECTIONS as VALID_PYTHON_SECTIONS
+
+__all__ = [
+    'existing_directory',
+    'error',
+    'create_argument_parser',
+    'main',
+]
+
+_LANG_PYTHON = 'python'
+_PROGRAM_NAME = 'jcloud-docsgen'
+
+
+def existing_directory(path: str) -> pathlib.Path:
+    _path = path
+    path = pathlib.Path(_path)
+    if not path.exists():
+        raise argparse.ArgumentTypeError(f'{_path}: no such file or directory')
+    if not path.is_dir():
+        raise argparse.ArgumentTypeError(f'{_path}: not a directory')
+    return path
+
+
+def error(message: str, exit_code: int = 1):
+    """
+    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
+    """
+
+    print(f'{_PROGRAM_NAME}: error: {message}', file=sys.stderr)
+    return exit_code
+
+
+def create_argument_parser() -> argparse.ArgumentParser:
+    """
+    Prepares a parser to parse the command-line arguments using
+    argparse.
+
+    :return: The parser.
+    :rtype: argparse.ArgumentParser
+    """
+
+    common_parser = argparse.ArgumentParser(add_help=False)
+    common_parser.add_argument(
+        'project_directory',
+        type=existing_directory,
+        nargs='?',
+        default=pathlib.Path('.'),
+        help='The directory of the project',
+    )
+    common_parser.add_argument(
+        '-o',
+        '--output-dir',
+        type=pathlib.Path,
+        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()
+
+    subparsers = argument_parser.add_subparsers(
+        dest='language',
+        required=True,
+    )
+
+    python_parser = subparsers.add_parser(
+        _LANG_PYTHON,
+        parents=[common_parser],
+        help='generate documentation for Python project',
+    )
+    python_parser.add_argument(
+        '-s',
+        '--sections',
+        nargs='+',
+        choices=VALID_PYTHON_SECTIONS,
+        help='the sections to be included in the documentation',
+    )
+    python_parser.add_argument(
+        '-S',
+        '--sections-exclude',
+        nargs='+',
+        default=[],
+        choices=VALID_PYTHON_SECTIONS,
+        help=(
+            'the sections to be excluded in the documentation. '
+            'If a section shall be included AND excluded, it is excluded.'
+        ),
+    )
+    python_parser.add_argument(
+        '-H',
+        '--allow-html',
+        action='store_true',
+        help=(
+            'indicates whether HTML is allowed in the documentation. '
+            'By default, HTML is disabled.'
+        ),
+    )
+    python_parser.add_argument(
+        '-T',
+        '--allow-tables',
+        action='store_true',
+        help=(
+            'indicates whether Markdown tables are allowed in the '
+            'documentation. By default, Markdown tables are disabled. '
+            'Warning: Markdown tables are not CommonMark.'
+        ),
+    )
+
+    return argument_parser
+
+
+def main(argv=None) -> int:
+    argument_parser = create_argument_parser()
+    args = argument_parser.parse_args(argv)
+
+    try:
+        if args.language == _LANG_PYTHON:
+            from .languages.python import generate
+
+            generate(
+                args.project_directory,
+                args.output_dir,
+                include_sections=args.sections,
+                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')
+    except NotADirectoryError as exc:
+        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:
+        return error(f'{exc.filename}: permission denied')
+    except OSError as exc:
+        return error(f'{exc.filename}: {exc.args[1]}')
+    except UnicodeError:
+        return error('invalid text encoding')
+    except SyntaxError:
+        # TODO: add a custom exception class to clearify that a project
+        # parsing syntax error is meant.
+        return error('syntax error in project source code')
+    except KeyboardInterrupt:
+        return 130
+    except BrokenPipeError:
+        return 141
+
+    return 0

src/jcloud_docsgen/cli/languages/__init__.py

@@ -0,0 +1,19 @@
+# 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.
+
+from . import python
+
+__all__ = [
+    'python',
+]

src/jcloud_docsgen/cli/languages/python.py

@@ -0,0 +1,155 @@
+# 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 pathlib
+
+from ...core.python import (
+    PythonDefinitionDocumentationIncludeSections,
+    PythonDocumentationGenerator,
+)
+
+__all__ = [
+    'VALID_SECTIONS',
+    'parse_sections_list',
+    'generate',
+]
+
+VALID_SECTIONS = list(
+    PythonDefinitionDocumentationIncludeSections()._args.keys()
+)
+
+
+def parse_sections_list(
+    include_sections: list[str] | None = None,
+    exclude_sections: list[str] = [],
+) -> PythonDefinitionDocumentationIncludeSections:
+    """
+    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
+    """
+
+    if include_sections is None:
+        include_sections = VALID_SECTIONS[:]
+
+    for section in exclude_sections:
+        while section in include_sections:
+            del include_sections[include_sections.index(section)]
+
+    return PythonDefinitionDocumentationIncludeSections(
+        signature='signature' in include_sections,
+        returns='returns' in include_sections,
+        params='params' in include_sections,
+        exceptions='exceptions' in include_sections,
+        examples='examples' in include_sections,
+        docstring='docstring' in include_sections,
+        bases='bases' in include_sections,
+        decorators='decorators' in include_sections,
+        class_body='class_body' in include_sections,
+    )
+
+
+def _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:
+    """
+    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
+    """
+
+    docs_generator = PythonDocumentationGenerator(
+        project_directory,
+        output_directory,
+        include_sections=include_sections,
+        allow_html=allow_html,
+        allow_tables=allow_tables,
+    )
+    docs_generator.generate_documentation(force)
+
+
+def 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:
+    """
+    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
+    """
+
+    sections = parse_sections_list(include_sections, exclude_sections)
+
+    _generate(
+        project_directory,
+        output_directory,
+        include_sections=sections,
+        allow_html=allow_html,
+        allow_tables=allow_tables,
+        force=force,
+    )

src/jcloud_docsgen/core/__init__.py

@@ -15,5 +15,5 @@
 from . import python
 
 __all__ = [
-    'python'
+    'python',
 ]

src/jcloud_docsgen/core/python/__init__.py

@@ -12,11 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from ._core import *
-from ._core import __all__ as _core__all__
 from . import namespaces
+from ._core import *  # noqa: F403
+from ._core import __all__ as _core__all__
 
 __all__ = [
     *_core__all__,
-    'namespaces'
+    'namespaces',
 ]

src/jcloud_docsgen/core/python/arguments.py

@@ -13,20 +13,26 @@
 # limitations under the License.
 
 from __future__ import annotations
-from enum import Enum
-from typing import Union
+
 import ast
-from ...utils import assert_that_is_instance
-from ...exceptions import InvalidPythonIdentifierError, InvalidPythonAnnotationError, PythonArgumentStructureError
 import keyword
 import types
+from enum import Enum
+
+from ...exceptions import (
+    InvalidPythonAnnotationError,
+    InvalidPythonIdentifierError,
+    PythonArgumentStructureError,
+)
+from ...utils import assert_that_is_instance
 
 __all__ = [
     'PythonArgumentKind',
     'PythonFunctionArgument',
-    'PythonASTArgumentsListParser'
+    'PythonASTArgumentsListParser',
 ]
 
+
 class PythonArgumentKind(Enum):
     NORMAL = 0
     POSITIONAL_ONLY = 1
@@ -34,8 +40,9 @@ class PythonArgumentKind(Enum):
     VARARG = 3
     KWARGS = 4
 
+
 class PythonFunctionArgument:
-    '''
+    """
     Represents an argument of a Python function.
 
     :param name: The name of the argument.
@@ -43,12 +50,18 @@ class PythonFunctionArgument:
     :param kind: The kind of the argument.
     :type kind: ArgumentKind
     :param default: The default value of the argument.
-    :type default: Union[str, None]
+    :type default: str | None
     :param annotation: The type annotation of the argument.
-    :type annotation: Union[str, None]
-    '''
+    :type annotation: str | None
+    """
 
-    def __init__(self, name: str, kind: PythonArgumentKind, default: Union[str, None], annotation: Union[str, None]) -> None:
+    def __init__(
+        self,
+        name: str,
+        kind: PythonArgumentKind,
+        default: str | None,
+        annotation: str | None,
+    ) -> None:
         assert_that_is_instance(name, str)
         assert_that_is_instance(kind, PythonArgumentKind)
         assert_that_is_instance(default, (str, types.NoneType))
@@ -56,42 +69,65 @@ class PythonFunctionArgument:
 
         # check whether name is a valid identifier
         if not name or not name.isidentifier() or keyword.iskeyword(name):
-            raise InvalidPythonIdentifierError('invalid identifier', identifier = name)
-        
+            raise InvalidPythonIdentifierError(
+                'invalid identifier',
+                identifier=name,
+            )
+
         # check whether the annotation is a valid annotation
         # Currently, it is only checked whether the parameter is not
         # empty.
         if annotation is not None and not annotation:
-            raise InvalidPythonAnnotationError('invalid annotation', annotation = annotation)
+            raise InvalidPythonAnnotationError(
+                'invalid annotation',
+                annotation=annotation,
+            )
 
         self.name = name
         self.kind = kind
         self.default = default
         self.annotation = annotation
-        
-        if self.kind in (PythonArgumentKind.VARARG, PythonArgumentKind.KWARGS) and self.default is not None:
-            raise PythonArgumentStructureError('* or ** arguments cannot have default values', definition = self.signature_repr())
+
+        if (
+            self.kind
+            in (
+                PythonArgumentKind.VARARG,
+                PythonArgumentKind.KWARGS,
+            )
+            and self.default is not None
+        ):
+            raise PythonArgumentStructureError(
+                '* or ** arguments cannot have default values',
+                definition=self.signature_repr(),
+            )
 
     def __eq__(self, value: PythonFunctionArgument) -> bool:
         if not isinstance(value, PythonFunctionArgument):
             return False
-        return self.name == value.name and self.kind == value.kind and self.default == value.default and self.annotation == value.annotation
-    
+        return (
+            self.name == value.name
+            and self.kind == value.kind
+            and self.default == value.default
+            and self.annotation == value.annotation
+        )
+
     def __repr__(self) -> str:
-        return type(self).__name__ + repr((
-            self.name,
-            self.kind,
-            self.default,
-            self.annotation
-        ))
+        return type(self).__name__ + repr(
+            (
+                self.name,
+                self.kind,
+                self.default,
+                self.annotation,
+            )
+        )
 
     def signature_repr(self) -> str:
-        '''
+        """
         Returns the function signature representation of the argument.
 
         :return: The string representation of the argument.
         :rtype: str
-        '''
+        """
 
         if self.kind == PythonArgumentKind.KWARGS:
             str_repr = '**'
@@ -106,68 +142,154 @@ class PythonFunctionArgument:
             str_repr += ': ' + self.annotation
 
         if self.default is not None:
-            str_repr += ' = ' + self.default
+            if self.annotation is None:
+                str_repr += '=' + self.default
+            else:
+                str_repr += ' = ' + self.default
 
         return str_repr
 
+
 class PythonASTArgumentsListParser:
-    '''
+    """
     A parser for making ``PythonFunctionArgument`` objects from an
     ``ast.arguments`` arguments list.
 
     :param ast_arguments_list: The ``ast.arguments`` arguments list.
     :type ast_arguments_list: ast.arguments
-    '''
+    """
 
-    def __init__(self, ast_arguments_list: ast.arguments) ->  None:
+    def __init__(self, ast_arguments_list: ast.arguments) -> None:
         self.ast_arguments_list = ast_arguments_list
 
     def to_argument_list(self) -> list[PythonFunctionArgument]:
-        '''
+        """
         Converts the AST arguments list to a list of Python function
         argument objects.
 
         :return: The list of Python function argument objects.
         :rtype: list[PythonFunctionArgument]
-        '''
+        """
 
-        defaults = [None for _ in range(len(
-            self.ast_arguments_list.posonlyargs +
-            self.ast_arguments_list.args +
-            self.ast_arguments_list.kwonlyargs
-        ) - len(self.ast_arguments_list.defaults) - len(self.ast_arguments_list.kw_defaults))] + \
-        [ast.unparse(d) for d in self.ast_arguments_list.defaults] + \
-        [ast.unparse(d) if d is not None else None   for d in self.ast_arguments_list.kw_defaults]
+        defaults = (
+            [
+                None
+                for _ in range(
+                    len(
+                        self.ast_arguments_list.posonlyargs
+                        + self.ast_arguments_list.args
+                        + self.ast_arguments_list.kwonlyargs
+                    )
+                    - len(self.ast_arguments_list.defaults)
+                    - len(self.ast_arguments_list.kw_defaults)
+                )
+            ]
+            + [ast.unparse(d) for d in self.ast_arguments_list.defaults]
+            + [
+                ast.unparse(d) if d is not None else None
+                for d in self.ast_arguments_list.kw_defaults
+            ]
+        )
 
         i = 0
         arguments = []
         for arg in self.ast_arguments_list.posonlyargs:
             if arg.annotation is None:
-                arguments.append(PythonFunctionArgument(arg.arg, PythonArgumentKind.POSITIONAL_ONLY, defaults[i], None))
+                arguments.append(
+                    PythonFunctionArgument(
+                        arg.arg,
+                        PythonArgumentKind.POSITIONAL_ONLY,
+                        defaults[i],
+                        None,
+                    ),
+                )
             else:
-                arguments.append(PythonFunctionArgument(arg.arg, PythonArgumentKind.POSITIONAL_ONLY, defaults[i], ast.unparse(arg.annotation)))
+                arguments.append(
+                    PythonFunctionArgument(
+                        arg.arg,
+                        PythonArgumentKind.POSITIONAL_ONLY,
+                        defaults[i],
+                        ast.unparse(arg.annotation),
+                    ),
+                )
             i += 1
         for arg in self.ast_arguments_list.args:
             if arg.annotation is None:
-                arguments.append(PythonFunctionArgument(arg.arg, PythonArgumentKind.NORMAL, defaults[i], None))
+                arguments.append(
+                    PythonFunctionArgument(
+                        arg.arg,
+                        PythonArgumentKind.NORMAL,
+                        defaults[i],
+                        None,
+                    ),
+                )
             else:
-                arguments.append(PythonFunctionArgument(arg.arg, PythonArgumentKind.NORMAL, defaults[i], ast.unparse(arg.annotation)))
+                arguments.append(
+                    PythonFunctionArgument(
+                        arg.arg,
+                        PythonArgumentKind.NORMAL,
+                        defaults[i],
+                        ast.unparse(arg.annotation),
+                    ),
+                )
             i += 1
         if self.ast_arguments_list.vararg is not None:
             if self.ast_arguments_list.vararg.annotation is None:
-                arguments.append(PythonFunctionArgument(self.ast_arguments_list.vararg.arg, PythonArgumentKind.VARARG, None, None))
+                arguments.append(
+                    PythonFunctionArgument(
+                        self.ast_arguments_list.vararg.arg,
+                        PythonArgumentKind.VARARG,
+                        None,
+                        None,
+                    ),
+                )
             else:
-                arguments.append(PythonFunctionArgument(self.ast_arguments_list.vararg.arg, PythonArgumentKind.VARARG, None, ast.unparse(self.ast_arguments_list.vararg.annotation)))
+                arguments.append(
+                    PythonFunctionArgument(
+                        self.ast_arguments_list.vararg.arg,
+                        PythonArgumentKind.VARARG,
+                        None,
+                        ast.unparse(self.ast_arguments_list.vararg.annotation),
+                    ),
+                )
         for arg in self.ast_arguments_list.kwonlyargs:
             if arg.annotation is None:
-                arguments.append(PythonFunctionArgument(arg.arg, PythonArgumentKind.KEYWORD_ONLY, defaults[i], None))
+                arguments.append(
+                    PythonFunctionArgument(
+                        arg.arg,
+                        PythonArgumentKind.KEYWORD_ONLY,
+                        defaults[i],
+                        None,
+                    ),
+                )
             else:
-                arguments.append(PythonFunctionArgument(arg.arg, PythonArgumentKind.KEYWORD_ONLY, defaults[i], ast.unparse(arg.annotation)))
+                arguments.append(
+                    PythonFunctionArgument(
+                        arg.arg,
+                        PythonArgumentKind.KEYWORD_ONLY,
+                        defaults[i],
+                        ast.unparse(arg.annotation),
+                    ),
+                )
             i += 1
         if self.ast_arguments_list.kwarg is not None:
             if self.ast_arguments_list.kwarg.annotation is None:
-                arguments.append(PythonFunctionArgument(self.ast_arguments_list.kwarg.arg, PythonArgumentKind.KWARGS, None, None))
+                arguments.append(
+                    PythonFunctionArgument(
+                        self.ast_arguments_list.kwarg.arg,
+                        PythonArgumentKind.KWARGS,
+                        None,
+                        None,
+                    ),
+                )
             else:
-                arguments.append(PythonFunctionArgument(self.ast_arguments_list.kwarg.arg, PythonArgumentKind.KWARGS, None, ast.unparse(self.ast_arguments_list.kwarg.annotation)))
+                arguments.append(
+                    PythonFunctionArgument(
+                        self.ast_arguments_list.kwarg.arg,
+                        PythonArgumentKind.KWARGS,
+                        None,
+                        ast.unparse(self.ast_arguments_list.kwarg.annotation),
+                    ),
+                )
 
         return arguments

src/jcloud_docsgen/core/python/definitions.py

@@ -13,55 +13,66 @@
 # limitations under the License.
 
 from __future__ import annotations
-from typing import Union
+
 import ast
-from .arguments import PythonFunctionArgument, PythonASTArgumentsListParser
-from .docstrings import PythonDocstring
 import keyword
+import types
+
 from ...exceptions import InvalidPythonIdentifierError
 from ...utils import assert_that_is_instance
-import types
+from .arguments import PythonASTArgumentsListParser, PythonFunctionArgument
+from .docstrings import PythonDocstring
 
 __all__ = [
     'PythonDefinition',
     'PythonFunctionDefinition',
     'PythonAsyncFunctionDefinition',
-    'PythonClassDefinition'
+    'PythonClassDefinition',
 ]
 
-def _python_docstring(doc: Union[str, None]) -> Union[PythonDocstring, None]:
-    '''
+
+def _python_docstring(doc: str | None) -> PythonDocstring | None:
+    """
     Returns the PythonDocstring object if the docstring is a string and
     not ``None``.
 
     :param doc: The docstring.
-    :type doc: Union[str, None]
+    :type doc: str | None
 
     :return: The PythonDocstring object or ``None``.
-    :rtype: Union[PythonDocstring, None]
-    '''
+    :rtype: PythonDocstring | None
+    """
 
     return PythonDocstring(doc) if doc is not None else None
 
+
 class PythonDefinition:
-    '''
+    """
     A base class for Python definition (a class, function or asynchronous
     function definition) classes.
 
     :param name: The name of the definition.
     :type name: str
     :param doc: The docstring.
-    :type doc: Union[PythonDocstring, None]
+    :type doc: PythonDocstring | None
     :param decorators: The definition decorators.
     :type decorators: list[str]
 
     :raises InvalidPythonIdentifierError: If the name is not a valid
                                           Python identifier.
-    '''
+    """
 
-    def __init__(self, name: str, doc: Union[PythonDocstring, None], decorators: list[str]) -> None:
+    def __init__(
+        self,
+        name: str,
+        doc: PythonDocstring | None,
+        decorators: list[str],
+    ) -> None:
         if keyword.iskeyword(name) or not name.isidentifier() or not name:
-            raise InvalidPythonIdentifierError('invalid identifier', identifier = name)
+            raise InvalidPythonIdentifierError(
+                'invalid identifier',
+                identifier=name,
+            )
 
         assert_that_is_instance(doc, (PythonDocstring, types.NoneType))
 
@@ -73,7 +84,7 @@ class PythonDefinition:
         return (
             self.name,
             self.doc,
-            self.decorators
+            self.decorators,
         )
 
     def __repr__(self) -> str:
@@ -81,26 +92,27 @@ class PythonDefinition:
 
     @classmethod
     def from_node(cls, node: ast.stmt) -> PythonDefinition:
-        '''
+        """
         From an AST node.
 
         :param node: The AST node.
         :type node: ast.stmt
-        '''
+        """
 
         return cls(
             node.name,
             _python_docstring(ast.get_docstring(node)),
-            [ast.unparse(d) for d in node.decorator_list]
+            [ast.unparse(d) for d in node.decorator_list],
         )
-    
+
     def __eq__(self, value: object) -> bool:
         if not isinstance(value, PythonDefinition):
             return False
         return self._arg_list() == value._arg_list()
 
+
 class PythonFunctionDefinition(PythonDefinition):
-    '''
+    """
     A PythonDefinition subclass representing a Python function
     definition.
 
@@ -109,17 +121,24 @@ class PythonFunctionDefinition(PythonDefinition):
     :param args: The arguments.
     :type args: list[PythonFunctionArgument]
     :param returns: The return type of the function or class.
-    :type returns: Union[str, None]
+    :type returns: str | None
     :param doc: The docstring.
-    :type doc: Union[PythonDocstring, None]
+    :type doc: PythonDocstring | None
     :param decorators: The definition decorators.
     :type decorators: list[str]
 
     :raises InvalidPythonIdentifierError: If the name is not a valid
                                           Python identifier.
-    '''
+    """
 
-    def __init__(self, name: str, args: list[PythonFunctionArgument], returns: Union[str, None], doc: Union[PythonDocstring, None], decorators: list[str]) -> None:
+    def __init__(
+        self,
+        name: str,
+        args: list[PythonFunctionArgument],
+        returns: str | None,
+        doc: PythonDocstring | None,
+        decorators: list[str],
+    ) -> None:
         super().__init__(name, doc, decorators)
         self.args = args
         self.returns = returns
@@ -130,28 +149,29 @@ class PythonFunctionDefinition(PythonDefinition):
             self.args,
             self.returns,
             self.doc,
-            self.decorators
+            self.decorators,
         )
 
     @classmethod
     def from_node(cls, node: ast.stmt) -> PythonFunctionDefinition:
-        '''
+        """
         From an AST node.
 
         :param node: The AST node.
         :type node: ast.stmt
-        '''
+        """
 
         return cls(
             node.name,
             PythonASTArgumentsListParser(node.args).to_argument_list(),
             ast.unparse(node.returns) if node.returns is not None else None,
             _python_docstring(ast.get_docstring(node)),
-            [ast.unparse(d) for d in node.decorator_list]
+            [ast.unparse(d) for d in node.decorator_list],
         )
 
+
 class PythonAsyncFunctionDefinition(PythonFunctionDefinition):
-    '''
+    """
     A PythonDefinition subclass representing an asynchronous Python function
     definition.
 
@@ -160,18 +180,19 @@ class PythonAsyncFunctionDefinition(PythonFunctionDefinition):
     :param args: The arguments.
     :type args: list[PythonFunctionArgument]
     :param returns: The return type of the function or class.
-    :type returns: Union[str, None]
+    :type returns: str | None
     :param doc: The docstring.
-    :type doc: Union[PythonDocstring, None]
+    :type doc: PythonDocstring | None
     :param decorators: The definition decorators.
     :type decorators: list[str]
 
     :raises InvalidPythonIdentifierError: If the name is not a valid
                                           Python identifier.
-    '''
+    """
+
 
 class PythonClassDefinition(PythonDefinition):
-    '''
+    """
     A PythonDefinition subclass representing a Python class definition.
 
     :param name: The name of the definition.
@@ -179,7 +200,7 @@ class PythonClassDefinition(PythonDefinition):
     :param bases: The base classes.
     :type bases: list[str]
     :param doc: The docstring.
-    :type doc: Union[PythonDocstring, None]
+    :type doc: PythonDocstring | None
     :param decorators: The definition decorators.
     :type decorators: list[str]
     :param body:
@@ -187,9 +208,16 @@ class PythonClassDefinition(PythonDefinition):
 
     :raises InvalidPythonIdentifierError: If the name is not a valid
                                           Python identifier.
-    '''
+    """
 
-    def __init__(self, name: str, bases: list[str], doc: Union[PythonDocstring, None], decorators: list[str], body: list[PythonDefinition]) -> None:
+    def __init__(
+        self,
+        name: str,
+        bases: list[str],
+        doc: PythonDocstring | None,
+        decorators: list[str],
+        body: list[PythonDefinition],
+    ) -> None:
         super().__init__(name, doc, decorators)
         self.bases = bases
         self.body = body
@@ -200,17 +228,17 @@ class PythonClassDefinition(PythonDefinition):
             self.bases,
             self.doc,
             self.decorators,
-            self.body
+            self.body,
         )
-    
+
     @classmethod
     def from_node(cls, node: ast.stmt) -> PythonClassDefinition:
-        '''
+        """
         From an AST node.
 
         :param node: The AST node.
         :type node: ast.stmt
-        '''
+        """
 
         return cls(
             node.name,
@@ -220,13 +248,12 @@ class PythonClassDefinition(PythonDefinition):
             [
                 PythonFunctionDefinition.from_node(expr)
                 if isinstance(expr, ast.FunctionDef)
-
                 else PythonAsyncFunctionDefinition.from_node(expr)
                 if isinstance(expr, ast.AsyncFunctionDef)
-
                 else PythonClassDefinition.from_node(expr)
-
                 for expr in node.body
-                if isinstance(expr, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef))
-            ]
+                if isinstance(
+                    expr, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+                )
+            ],
         )

src/jcloud_docsgen/core/python/docstrings.py

@@ -12,38 +12,36 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from enum import Enum
 import docstring_parser
 
-__all__ = [
-    'PythonDocstring'
-]
+__all__ = ['PythonDocstring']
+
 
 class PythonDocstring:
-    '''
+    """
     Represents a Python docstring.
-    
+
     :param docstring: The docstring as a string.
     :type docstring: str
-    '''
+    """
 
     def __init__(self, docstring: str) -> None:
         self.docstring = docstring
 
     def __repr__(self) -> str:
         return type(self).__name__ + '(' + repr(self.docstring) + ')'
-    
+
     def __eq__(self, value) -> bool:
         if not isinstance(value, type(self)):
             return False
         return self.docstring == value.docstring
-    
+
     def parse(self) -> docstring_parser.Docstring:
-        '''
+        """
         Parses the docstring.
 
         :return: The parsed docstring.
         :rtype: docstring_parser.Docstring
-        '''
+        """
 
         return docstring_parser.parse(self.docstring)

src/jcloud_docsgen/core/python/namespaces.py

@@ -13,55 +13,101 @@
 # limitations under the License.
 
 from __future__ import annotations
-from ...exceptions import InvalidNamespaceError, NamespaceNotFoundError, NamespaceExistsError
+
+import keyword
+from typing import TypeAlias, Union
+
+from ...exceptions import (
+    InvalidNamespaceError,
+    NamespaceExistsError,
+    NamespaceNotFoundError,
+)
 from ...utils import assert_that_is_instance
-from typing import Union, TypeAlias, Dict, List
 
 __all__ = [
+    'validate_namespace_name',
     'PythonNamespace',
     'PythonPackageNamespace',
-    'PythonModuleNamespace'
+    '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 name.strip():
-            raise InvalidNamespaceError('invalid namespace', namespace_identifier = name)
+        if not validate_namespace_name(name):
+            raise InvalidNamespaceError(
+                'invalid namespace', namespace_identifier=name
+            )
 
         self.name = name
 
     def __repr__(self) -> str:
         return f'{type(self).__name__}({self.name!r})'
 
-PythonPackageNamespaceDictType: TypeAlias = Dict[str, Union[str, 'PythonPackageNamespaceDictType']]
+
+PythonPackageNamespaceDictType: TypeAlias = dict[
+    str,
+    Union[
+        str,
+        'PythonPackageNamespaceDictType',
+    ],
+]
+
 
 class PythonPackageNamespace(PythonNamespace):
-    '''
+    """
     A subclass of ``PythonNamespace`` for Python package namespaces.
 
     :param name: The name of the namespace.
     :type name: str
     :param sub_namespaces: The sub-namespaces.
     :type sub_namespaces: list[PythonNamespace]
-    '''
 
-    def __init__(self, name: str, sub_namespaces: List[PythonNamespace]) -> None:
+    :raises InvalidNamespaceError: If the namespace name is invalid.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        sub_namespaces: list[PythonNamespace],
+    ) -> None:
         assert_that_is_instance(sub_namespaces, list)
 
         super().__init__(name)
 
         self._sub_namespaces = sub_namespaces
 
-    def namespace(self, sub_namespaces: List[str]) -> PythonNamespace:
-        '''
+    def namespace(self, sub_namespaces: list[str]) -> PythonNamespace:
+        """
         Returns the namespace object with a specific identifier, such as
         ``['package', 'subpackage', 'module']``.
 
@@ -74,7 +120,7 @@ class PythonPackageNamespace(PythonNamespace):
 
         :return: The namespace.
         :rtype: PythonNamespace
-        '''
+        """
 
         if not sub_namespaces:
             raise InvalidNamespaceError('invalid namespace')
@@ -94,31 +140,38 @@ class PythonPackageNamespace(PythonNamespace):
         else:
             return sub_namespace
 
-    def _sub_namespaces_names(self, package: PythonPackageNamespace) -> PythonPackageNamespaceDictType:
-        '''
+    def _sub_namespaces_names(
+        self,
+        package: PythonPackageNamespace,
+    ) -> PythonPackageNamespaceDictType:
+        """
         Returns the names of all sub-namespaces of the specified package
         namespace and keeps the package structure.
-        
+
         :param package: The package.
         :type package: PythonPackageNamespace
 
         :return: The names if all sub-namespaces.
         :rtype: PythonPackageNamespaceDictType
-        '''
+        """
 
         return {
-            sn.name: self._sub_namespaces_names(sn) if isinstance(sn, PythonPackageNamespace) else sn.name
+            sn.name: (
+                self._sub_namespaces_names(sn)
+                if isinstance(sn, PythonPackageNamespace)
+                else sn.name
+            )
             for sn in package._sub_namespaces
         }
-    
+
     def sub_namespace_names(self) -> PythonPackageNamespaceDictType:
-        '''
+        """
         Returns the names of all sub-namespaces and keeps the package
         structure.
-        
+
         :return: The names if all sub-namespaces.
         :rtype: PythonPackageNamespaceDictType
-        '''
+        """
 
         return self._sub_namespaces_names(self)
 
@@ -126,7 +179,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 self.name != value.name:
+        if not (isinstance(value, type(self)) and self.name == value.name):
             return False
 
         return value.sub_namespace_names() == self.sub_namespace_names()
@@ -135,7 +188,7 @@ class PythonPackageNamespace(PythonNamespace):
         return type(self).__name__ + repr((self.name, self._sub_namespaces))
 
     def __getitem__(self, name: str) -> PythonNamespace:
-        '''
+        """
         Returns a namespace with the specified name.
 
         :param name: The name of the namespace
@@ -145,16 +198,19 @@ class PythonPackageNamespace(PythonNamespace):
 
         :return: The namespace
         :rtype: PythonNamespace
-        '''
+        """
 
         for sub in self._sub_namespaces:
             if sub.name == name:
                 return sub
 
-        raise NamespaceNotFoundError('no such namespace', namespace_identifier = name)
-    
+        raise NamespaceNotFoundError(
+            'no such namespace',
+            namespace_identifier=name,
+        )
+
     def add(self, namespace: PythonNamespace) -> None:
-        '''
+        """
         Adds a namespace.
 
         :param namespace: The namespace to add.
@@ -163,27 +219,31 @@ class PythonPackageNamespace(PythonNamespace):
         :raises NamespaceExistsError: If a namespace with the name of the
                                       namespace that is attempted to add
                                       already exists.
-        '''
+        """
         try:
             self.__getitem__(namespace.name)
-            raise NamespaceExistsError('namespace already exists', namespace_identifier = namespace.name)
+            raise NamespaceExistsError(
+                'namespace already exists',
+                namespace_identifier=namespace.name,
+            )
         except NamespaceNotFoundError:
             self._sub_namespaces.append(namespace)
 
     @property
-    def sub_namespaces(self) -> List[PythonNamespace]:
+    def sub_namespaces(self) -> list[PythonNamespace]:
         return self._sub_namespaces
 
+
 class PythonModuleNamespace(PythonNamespace):
-    '''
+    """
     A subclass of ``PythonNamespace`` for Python module namespaces.
 
     :param name: The name of the namespace.
     :type name: str
-    '''
+    """
 
     def __init__(self, name: str) -> None:
         super().__init__(name)
 
     def __eq__(self, value: PythonModuleNamespace) -> bool:
-        return self.name == value.name
+        return isinstance(value, type(self)) and self.name == value.name

src/jcloud_docsgen/exceptions.py

@@ -12,10 +12,28 @@
 # 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):
-    '''
+    """
     Base class for namespace errors.
-    '''
+    """
+
     def __init__(self, *args: object, namespace_identifier: str = '') -> None:
         super().__init__(*args)
         self.namespace_identifier = namespace_identifier
@@ -24,16 +42,27 @@ class NamespaceError(ValueError):
         if not self.args:
             return ''
         else:
-            return f'{self.args[0]}{": " if self.namespace_identifier and self.args[0] else ""}{self.namespace_identifier if self.args[0] else ""}'
-        
+            return (
+                self.args[0]
+                + (': ' if self.namespace_identifier and self.args[0] else '')
+                + (self.namespace_identifier if self.args[0] else '')
+            )
+
+
 class InvalidNamespaceError(NamespaceError): ...
+
+
 class NamespaceNotFoundError(NamespaceError): ...
+
+
 class NamespaceExistsError(NamespaceError): ...
 
+
 class PythonIdentifierError(ValueError):
-    '''
+    """
     Base class for Python identifier errors.
-    '''
+    """
+
     def __init__(self, *args: object, identifier: str = '') -> None:
         super().__init__(*args)
         self.identifier = identifier
@@ -42,14 +71,21 @@ class PythonIdentifierError(ValueError):
         if not self.args:
             return ''
         else:
-            return f'{self.args[0]}{": " if self.identifier and self.args[0] else ""}{self.identifier if self.args[0] else ""}'
+            return (
+                self.args[0]
+                + (': ' if self.identifier and self.args[0] else '')
+                + (self.identifier if self.args[0] else '')
+            )
+
 
 class InvalidPythonIdentifierError(PythonIdentifierError): ...
 
+
 class PythonAnnotationError(ValueError):
-    '''
+    """
     Base class for Python annotation errors.
-    '''
+    """
+
     def __init__(self, *args: object, annotation: str = '') -> None:
         super().__init__(*args)
         self.annotation = annotation
@@ -58,14 +94,21 @@ class PythonAnnotationError(ValueError):
         if not self.args:
             return ''
         else:
-            return f'{self.args[0]}{": " if self.annotation and self.args[0] else ""}{self.annotation if self.args[0] else ""}'
+            return (
+                self.args[0]
+                + (': ' if self.annotation and self.args[0] else '')
+                + (self.annotation if self.args[0] else '')
+            )
+
 
 class InvalidPythonAnnotationError(PythonAnnotationError): ...
 
+
 class PythonDefinitionError(ValueError):
-    '''
+    """
     Base class for Python definition errors.
-    '''
+    """
+
     def __init__(self, *args: object, definition: str = '') -> None:
         super().__init__(*args)
         self.definition = definition
@@ -74,6 +117,20 @@ class PythonDefinitionError(ValueError):
         if not self.args:
             return ''
         else:
-            return f'{self.args[0]}{": " if self.definition and self.args[0] else ""}{self.definition if self.args[0] else ""}'
+            return (
+                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

@@ -12,50 +12,81 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-'''
+"""
 The utilities for jcloud_docsgen
-'''
+"""
 
-import pathlib
-import os
 import errno
-from typing import Union
+import os
+import pathlib
 import types
 
+try:
+    from warnings import deprecated
+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):
-    '''
+    """
     pathlib.Path subclass that is a directory.
 
     ExistingDirectory represents a filesystem path but it also checks
     whether the path exists and is not a file but a directory. It
     inherits from pathlib.Path.
-    '''
+    """
+
     def __init__(self, path, *args, **kwargs) -> None:
         if not os.path.exists(path):
-            raise FileNotFoundError(errno.ENOENT, 'no such file or directory', path)
+            raise FileNotFoundError(
+                errno.ENOENT,
+                'no such file or directory',
+                path,
+            )
         if not os.path.isdir(path):
             raise NotADirectoryError(errno.ENOTDIR, 'not a directory', path)
         super().__init__(*(path, *args), **kwargs)
 
+
+@deprecated('Use pathlib.Path instead.')
 class ExistingFile(pathlib.Path):
-    '''
+    """
     pathlib.Path subclass that is a file.
 
     ExistingFile represents a filesystem path but it also checks whether
     the path exists and is not a directory but a file. It inherits from
     pathlib.Path.
-    '''
+    """
+
     def __init__(self, path, *args, **kwargs) -> None:
         if not os.path.exists(path):
-            raise FileNotFoundError(errno.ENOENT, 'no such file or directory', path)
+            raise FileNotFoundError(
+                errno.ENOENT,
+                'no such file or directory',
+                path,
+            )
         if not os.path.isfile(path):
             raise IsADirectoryError(errno.EISDIR, 'is a directory', path)
         super().__init__(*(path, *args), **kwargs)
 
+
 def _quote(string: str, quotation_mark: str) -> str:
-    '''
+    """
     Quotes a string.
-    
+
     :param string: The string to quote
     :type string: str
     :param quotation_mark: The quotation mark
@@ -63,12 +94,17 @@ def _quote(string: str, quotation_mark: str) -> str:
 
     :return: The quoted string
     :rtype: str
-    '''
+    """
 
     return quotation_mark + string + quotation_mark
 
-def human_readable_list(ls: list, final_separator: str = 'and', quotation_mark: str = '') -> str:
-    '''
+
+def human_readable_list(
+    ls: list,
+    final_separator: str = 'and',
+    quotation_mark: str = '',
+) -> str:
+    """
     Generates a human-readable list from a list.
 
     :param ls: The list.
@@ -79,28 +115,39 @@ def human_readable_list(ls: list, final_separator: str = 'and', quotation_mark:
     :type final_separator: str
     :param quotation_mark: The characters that are inserted before and
                            after an element. Default is ''.
-    
+
     :return: The human-readable list.
     :rtype: str
-    '''
+    """
 
     # empty list
     if not ls:
         return ''
-    
+
     # list with one element
     if len(ls) == 1:
         return _quote(str(ls[0]), quotation_mark)
-    
-    return ', '.join(
-        [
-            _quote(str(obj), quotation_mark) # quote the string representation of the object
-            for obj in ls[:-1] # do not include the last element of the list
-        ]
-    ) + ' ' + final_separator + ' ' + _quote(str(ls[-1]), quotation_mark)
+
+    return (
+        ', '.join(
+            [
+                _quote(
+                    str(obj), quotation_mark
+                )  # quote the string representation of the object
+                for obj in ls[
+                    :-1
+                ]  # do not include the last element of the list
+            ],
+        )
+        + ' '
+        + final_separator
+        + ' '
+        + _quote(str(ls[-1]), quotation_mark)
+    )
+
 
 def _list_type_names(types: list[type]) -> list[str]:
-    '''
+    """
     Converts a list of types into a list of their names (``__name__``
     attribute)
 
@@ -109,13 +156,20 @@ def _list_type_names(types: list[type]) -> list[str]:
 
     :return: The list of the names of the types
     :rtype: list[str]
-    '''
+    """
 
     return [tp.__name__ for tp in types]
 
-def assert_that_is_instance(obj: object, class_or_tuple: Union[type, types.UnionType, tuple[type, ...]]) -> None:
-    if not isinstance(class_or_tuple, Union[type, types.UnionType, tuple]):
-        raise TypeError(f'class_or_tuple: expected \'Union[type, types.UnionType, tuple[type, ...]]\', \'got {type(class_or_tuple).__name__}\'')
+
+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)):
+        raise TypeError(
+            f"class_or_tuple: expected 'type | types.UnionType, tupl"
+            f"e[type, ...]', 'got {type(class_or_tuple).__name__}'",
+        )
     if not isinstance(obj, class_or_tuple):
         if isinstance(class_or_tuple, (tuple, types.UnionType)):
             if isinstance(class_or_tuple, types.UnionType):
@@ -124,13 +178,21 @@ def assert_that_is_instance(obj: object, class_or_tuple: Union[type, types.Union
                 exception_message_expected = 'either '
             else:
                 exception_message_expected = ''
-            exception_message_expected += human_readable_list(_list_type_names(class_or_tuple), 'or', '\'')
+            exception_message_expected += human_readable_list(
+                _list_type_names(class_or_tuple),
+                'or',
+                "'",
+            )
         else:
-            exception_message_expected = '\'' + class_or_tuple.__name__ + '\''
-        raise TypeError(f'expected {exception_message_expected}, got \'{type(obj).__name__}\'')
-    
-def non_empty_str(value: Union[str, None]) -> Union[str, None]:
-    '''
+            exception_message_expected = "'" + class_or_tuple.__name__ + "'"
+        raise TypeError(
+            f'expected {exception_message_expected}'
+            f", got '{type(obj).__name__}'"
+        )
+
+
+def non_empty_str(value: str | None) -> str | None:
+    """
     Returns the value or ``None``.
 
     Returns the value if it is not empty and not `Ǹone``; otherwise,
@@ -139,22 +201,26 @@ def non_empty_str(value: Union[str, None]) -> Union[str, None]:
                  of spaces, it is also considered empty.
 
     :param value: The value.
-    :type value: Union[str, None]
+    :type value: str | None
 
     :return: The value or ``None``.
-    :rtype: Union[str, None]
-    '''
+    :rtype: str | None
+    """
 
     if value is None:
         return None
-    
+
     if value.strip() == '':
         return None
 
     return value
 
-def get_relative_path_segments(path: pathlib.Path, root: pathlib.Path) -> list[str]:
-    '''
+
+def get_relative_path_segments(
+    path: pathlib.Path,
+    root: pathlib.Path,
+) -> list[str]:
+    """
     Returns the path segments relative to ``root``.
 
     :param path: The path.
@@ -164,12 +230,136 @@ def get_relative_path_segments(path: pathlib.Path, root: pathlib.Path) -> list[s
 
     :return: The path segments relative to ``root``.
     :rtype: list[str]
-    '''
+    """
 
     return list(
         path.resolve()
         .relative_to(
-            root.resolve()
+            root.resolve(),
         )
-        .parts
+        .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/integration/cli/test_cli.py

@@ -0,0 +1,36 @@
+# 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 subprocess
+import sys
+
+
+def test_cli():
+    result = subprocess.run(
+        [
+            sys.executable,
+            '-m',
+            'jcloud_docsgen',
+            '--help',
+        ],
+        capture_output=True,
+        text=True,
+    )
+    stdout = result.stdout.lower()
+    assert (
+        'usage:' in stdout
+        and 'positional arguments' in stdout
+        and 'options' in stdout
+        and '--help' in stdout
+    )

tests/unit/cli/python_project/expected/pkg/module.md

@@ -0,0 +1,20 @@
+# Module `pkg.module`
+
+## Function `f`
+
+Does something.
+
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `a` | `int` | normal | `42` | A parameter. |
+
+<details><summary><h3 style="display:inline">Docstring</h3></summary>Does something.
+
+:param a: A parameter.
+:type a: int
+
+:return: A string.
+:rtype: str</details>

tests/unit/cli/python_project/project/pkg/module.py

@@ -0,0 +1,11 @@
+def f(a: int = 42) -> str:
+    """
+    Does something.
+
+    :param a: A parameter.
+    :type a: int
+
+    :return: A string.
+    :rtype: str
+    """
+    ...

tests/unit/cli/test_parser.py

@@ -0,0 +1,43 @@
+# 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 jcloud_docsgen.cli.cli import create_argument_parser
+
+
+@pytest.mark.parametrize(
+    'lang',
+    [
+        'javascript',
+        'Python',
+        'PYTHON',
+    ],
+)
+def test_language_error(lang):
+    parser = create_argument_parser()
+
+    with pytest.raises(SystemExit):
+        parser.parse_args([lang])
+
+
+@pytest.mark.parametrize(
+    'lang',
+    [
+        'python',
+    ],
+)
+def test_language_success(lang):
+    parser = create_argument_parser()
+    parser.parse_args([lang])

tests/unit/cli/test_python.py

@@ -0,0 +1,214 @@
+# 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 pathlib
+import tempfile
+
+import pytest
+
+from jcloud_docsgen.cli.cli import create_argument_parser
+from jcloud_docsgen.cli.cli import main as cli_main
+from jcloud_docsgen.cli.languages.python import parse_sections_list
+from jcloud_docsgen.core.python import (
+    PythonDefinitionDocumentationIncludeSections,
+)
+
+
+@pytest.mark.parametrize(
+    'include,exclude,expected',
+    [
+        (
+            [],
+            [],
+            PythonDefinitionDocumentationIncludeSections(
+                signature=False,
+                returns=False,
+                params=False,
+                exceptions=False,
+                examples=False,
+                docstring=False,
+                bases=False,
+                decorators=False,
+                class_body=False,
+            ),
+        ),
+        (
+            [],
+            ['signature'],
+            PythonDefinitionDocumentationIncludeSections(
+                signature=False,
+                returns=False,
+                params=False,
+                exceptions=False,
+                examples=False,
+                docstring=False,
+                bases=False,
+                decorators=False,
+                class_body=False,
+            ),
+        ),
+        (
+            ['signature'],
+            ['signature'],
+            PythonDefinitionDocumentationIncludeSections(
+                signature=False,
+                returns=False,
+                params=False,
+                exceptions=False,
+                examples=False,
+                docstring=False,
+                bases=False,
+                decorators=False,
+                class_body=False,
+            ),
+        ),
+        (
+            ['signature'],
+            [],
+            PythonDefinitionDocumentationIncludeSections(
+                signature=True,
+                returns=False,
+                params=False,
+                exceptions=False,
+                examples=False,
+                docstring=False,
+                bases=False,
+                decorators=False,
+                class_body=False,
+            ),
+        ),
+        (
+            None,
+            [],
+            PythonDefinitionDocumentationIncludeSections(),
+        ),
+        (
+            ['signature', 'exceptions', 'bases', 'class_body'],
+            ['signature', 'bases'],
+            PythonDefinitionDocumentationIncludeSections(
+                signature=False,
+                returns=False,
+                params=False,
+                exceptions=True,
+                examples=False,
+                docstring=False,
+                bases=False,
+                decorators=False,
+                class_body=True,
+            ),
+        ),
+        (
+            None,
+            ['params', 'docstring'],
+            PythonDefinitionDocumentationIncludeSections(
+                signature=True,
+                returns=True,
+                params=False,
+                exceptions=True,
+                examples=True,
+                docstring=False,
+                bases=True,
+                decorators=True,
+                class_body=True,
+            ),
+        ),
+    ],
+)
+def test_parse_sections_list(include, exclude, expected):
+    assert parse_sections_list(include, exclude) == expected
+
+
+def test_sections_error():
+    parser = create_argument_parser()
+
+    with pytest.raises(SystemExit):
+        parser.parse_args(
+            [
+                'python',
+                '-s',
+                'param',  # correct: `params`
+            ]
+        )
+
+    with pytest.raises(SystemExit):
+        parser.parse_args(
+            [
+                'python',
+                '-s',
+                'params',
+                'docstrng',  # correct: `docstring`
+            ]
+        )
+
+
+def test_sections_success():
+    parser = create_argument_parser()
+
+    parser.parse_args(
+        [
+            'python',
+            '-s',
+            'params',
+        ]
+    )
+    parser.parse_args(
+        [
+            'python',
+            '-s',
+            'params',
+            'docstring',
+        ]
+    )
+
+
+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',
+                    '-s',
+                    'params',
+                    'docstring',
+                    '-HTo',
+                    str(output_dir),
+                    str(input_dir),
+                ]
+            )
+            == 1
+        )

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

@@ -12,51 +12,185 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from src.jcloud_docsgen.core.python import PythonDocumentationGenerator
-from src.jcloud_docsgen.core.python.namespaces import PythonModuleNamespace, PythonPackageNamespace
-from src.jcloud_docsgen.utils import ExistingDirectory
-import pytest
 import pathlib
+import tempfile
 
-@pytest.mark.parametrize('project_directory,docs_directory,expected_exception,expected_exception_msg', [
-    (1, 1, TypeError, 'expected \'ExistingDirectory\', got \'int\''),
-    (1, None, TypeError, 'expected \'ExistingDirectory\', got \'int\''),
-    (42, None, TypeError, 'expected \'ExistingDirectory\', got \'int\''),
-    (ExistingDirectory('tests'), 1, TypeError, 'expected \'ExistingDirectory\', got \'int\''),
-    (ExistingDirectory('tests/'), 1, TypeError, 'expected \'ExistingDirectory\', got \'int\''),
-    (1, ExistingDirectory('tests/'), TypeError, 'expected \'ExistingDirectory\', got \'int\''),
-    (1, ExistingDirectory('tests'), TypeError, 'expected \'ExistingDirectory\', got \'int\''),
-    (None, ExistingDirectory('tests'), TypeError, 'expected \'ExistingDirectory\', got \'NoneType\''),
-])
-def test_PythonDocumentationGenerator_exceptions(project_directory, docs_directory, expected_exception, expected_exception_msg):
-    with pytest.raises(expected_exception) as exc_info:
-        PythonDocumentationGenerator(project_directory, docs_directory)
-    assert str(exc_info.value) == expected_exception_msg
+import pytest
 
-@pytest.mark.parametrize('python_documentation_generator,expected', [
-    (PythonDocumentationGenerator(ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_1'), ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_1/docs')), []),
-    (PythonDocumentationGenerator(ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_2'), ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_2/docs')), [PythonPackageNamespace('pkg', [PythonModuleNamespace('module')])]),
-    (PythonDocumentationGenerator(ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_3'), ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_3/docs')), [PythonPackageNamespace('pkg', [PythonModuleNamespace('module'), PythonPackageNamespace('pkg', [PythonModuleNamespace('module2')])])]),
-])
-def test_PythonDocumentationGenerator_collect_modules(python_documentation_generator: PythonDocumentationGenerator, expected):
-    assert python_documentation_generator.namespace() == expected
+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('dir', [
-    d.name
-    for d in pathlib.Path('tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/').iterdir()
-])
-def test_generate_documentation(dir, expectdir):
-    with expectdir('test_PythonDocumentationGenerator/test_generate_documentation/' + dir) as d:
-        PythonDocumentationGenerator(
-            ExistingDirectory(
-                str(
-                    pathlib.Path('tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/') /
-                    dir /
-                    'project'
-                )
+
+@pytest.mark.parametrize(
+    'python_documentation_generator,expected',
+    [
+        (
+            PythonDocumentationGenerator(
+                pathlib.Path(
+                    'tests/unit/core/python/_core/test_project_dirs/pdir_1/src'
+                ),
+                pathlib.Path(
+                    'tests/unit/core/python/_core/test_project_dirs/pdir_1/docs'
+                ),
             ),
-            ExistingDirectory(str(d)),
-            allow_tables = True,
-            allow_html = False
-        ).generate_documentation(
-        ) # simplify the tests
+            [],
+        ),
+        (
+            PythonDocumentationGenerator(
+                pathlib.Path(
+                    'tests/unit/core/python/_core/test_project_dirs/pdir_2/src'
+                ),
+                pathlib.Path(
+                    'tests/unit/core/python/_core/test_project_dirs/pdir_2/docs'
+                ),
+            ),
+            [
+                PythonPackageNamespace(
+                    'pkg',
+                    [PythonModuleNamespace('module')],
+                ),
+            ],
+        ),
+        (
+            PythonDocumentationGenerator(
+                pathlib.Path(
+                    'tests/unit/core/python/_core/test_project_dirs/pdir_3/src'
+                ),
+                pathlib.Path(
+                    'tests/unit/core/python/_core/test_project_dirs/pdir_3/docs'
+                ),
+            ),
+            [
+                PythonPackageNamespace(
+                    'pkg',
+                    [
+                        PythonModuleNamespace('module'),
+                        PythonPackageNamespace(
+                            'pkg',
+                            [
+                                PythonModuleNamespace('module2'),
+                            ],
+                        ),
+                    ],
+                ),
+            ],
+        ),
+    ],
+)
+def test_PythonDocumentationGenerator_collect_modules(
+    python_documentation_generator: PythonDocumentationGenerator,
+    expected,
+):
+    assert (
+        python_documentation_generator.namespace().sub_namespaces
+    ) == expected
+
+
+@pytest.mark.parametrize(
+    'dir',
+    [
+        d.name
+        for d in pathlib.Path(
+            (
+                'tests/unit/core/python/_core/test_PythonDocume'
+                'ntationGenerator/test_generate_documentation/'
+            ),
+        ).iterdir()
+    ],
+)
+def test_generate_documentation(dir, expectdir):
+    with expectdir(
+        'test_PythonDocumentationGenerator/test_generate_documentation/' + dir
+    ) as d:
+        PythonDocumentationGenerator(
+            pathlib.Path(
+                str(
+                    pathlib.Path(
+                        (
+                            'tests/unit/core/python/_core/test_PythonDocume'
+                            'ntationGenerator/test_generate_documentation/'
+                        ),
+                    )
+                    / dir
+                    / 'project',
+                ),
+            ),
+            pathlib.Path(str(d)),
+            allow_tables=True,
+            allow_html=False,
+        ).generate_documentation(True)  # simplify the tests
+
+
+def test_creates_directory():
+    with tempfile.TemporaryDirectory() as output_dir:
+        output_dir = pathlib.Path(output_dir)
+        with tempfile.TemporaryDirectory() as project_dir:
+            project_dir = pathlib.Path(project_dir)
+
+            # The directory of the package
+            package_dir = project_dir / 'pkg'
+            assert not package_dir.exists()
+            package_dir.mkdir(parents=True, exist_ok=True)
+
+            # The actual output directory directory
+            docs_dir = output_dir / 'docs' / 'reference'
+            # It should not exist
+            assert not docs_dir.exists()
+
+            docs_generator = PythonDocumentationGenerator(
+                project_dir, docs_dir
+            )
+            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

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

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

@@ -6,4 +6,34 @@
 
 ```python
 func()
-```
+```
+
+## Function `func2`
+
+### Function signature
+
+```python
+func2(a: int, b: int = 42, c=42, d=42)
+```
+
+
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `a` | `int` | normal | -- | -- |
+| `b` | `int` | normal | `42` | -- |
+| `c` | `int` | normal | `42` | -- |
+| `d` | -- | normal | `42` | -- |
+
+
+
+
+
+
+
+### Docstring
+
+:param c:
+:type c: int

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,8 @@
+def func(): ...
+
+
+def func2(a: int, b: int = 42, c=42, d=42):
+    """
+    :param c:
+    :type c: int
+    """

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

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

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

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

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/exceptions.py

@@ -1,8 +1,10 @@
 class UserNotFoundError(Exception):
     """User does not exist."""
+
     pass
 
 
 class InvalidEmailError(Exception):
     """Email address is invalid."""
-    pass
+
+    pass

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

@@ -1,5 +1,4 @@
 from dataclasses import dataclass
-from typing import Optional
 
 
 @dataclass
@@ -7,7 +6,8 @@ class User:
     """
     Represents a user.
     """
+
     id: str
     name: str
     email: str
-    age: Optional[int] = None
+    age: int | None = 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
 
 
@@ -12,18 +12,17 @@ class UserService:
     def __init__(self, storage: InMemoryUserStorage):
         self.storage = storage
 
-    def create_user(self, user_id: str, name: str, email: str, age: int | None = None) -> User:
+    def create_user(
+        self, user_id: str, name: str, email: str, age: int | None = None
+    ) -> User:
         """
         Creates and stores a new user.
         """
         if not is_valid_email(email):
-            raise InvalidEmailError(f"Invalid email: {email}")
+            raise InvalidEmailError(f'Invalid email: {email}')
 
         user = User(
-            id=user_id,
-            name=normalize_name(name),
-            email=email,
-            age=age
+            id=user_id, name=normalize_name(name), email=email, age=age
         )
 
         self.storage.add(user)
@@ -45,4 +44,4 @@ class UserService:
         try:
             self.storage.delete(user_id)
         except KeyError:
-            raise UserNotFoundError(user_id)
+            raise UserNotFoundError(user_id)

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

@@ -1,4 +1,3 @@
-from typing import Dict, List
 from .models import User
 
 
@@ -9,7 +8,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."""
@@ -23,6 +22,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())
+        return list(self._users.values())

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

@@ -5,7 +5,7 @@ def is_valid_email(email: str) -> bool:
     """
     Checks whether an email address is valid.
     """
-    pattern = r"^[\w\.-]+@[\w\.-]+\.\w+$"
+    pattern = r'^[\w\.-]+@[\w\.-]+\.\w+$'
     return re.match(pattern, email) is not None
 
 
@@ -13,4 +13,4 @@ def normalize_name(name: str) -> str:
     """
     Removes extra spaces and formats the name.
     """
-    return " ".join(name.strip().split()).title()
+    return ' '.join(name.strip().split()).title()

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

@@ -12,49 +12,223 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import pathlib
+
+import pytest
+
 from src.jcloud_docsgen.core.python import PythonModuleDocumentationGenerator
 from src.jcloud_docsgen.exceptions import InvalidNamespaceError
-import pytest
-from src.jcloud_docsgen.utils import ExistingFile, ExistingDirectory
 
-@pytest.mark.parametrize('module_path,src_directory,expected_exception,expected_exception_msg', [
-    (1, 1, TypeError, 'expected \'ExistingFile\', got \'int\''),
-    (1, None, TypeError, 'expected \'ExistingFile\', got \'int\''),
-    (42, None, TypeError, 'expected \'ExistingFile\', got \'int\''),
-    (ExistingFile('tests/unit/utils/test_file'), 1, TypeError, 'expected either \'ExistingDirectory\' or \'NoneType\', got \'int\''),
-    (ExistingDirectory('tests/'), 1, TypeError, 'expected \'ExistingFile\', got \'ExistingDirectory\''),
-    (ExistingDirectory('tests'), 1, TypeError, 'expected \'ExistingFile\', got \'ExistingDirectory\''),
-    (1, ExistingDirectory('tests/'), TypeError, 'expected \'ExistingFile\', got \'int\''),
-    (1, ExistingDirectory('tests'), TypeError, 'expected \'ExistingFile\', got \'int\''),
-    (None, ExistingDirectory('tests'), TypeError, 'expected \'ExistingFile\', got \'NoneType\''),
-    (None, None, TypeError, 'expected \'ExistingFile\', got \'NoneType\''),
-    (1, None, TypeError, 'expected \'ExistingFile\', got \'int\''),
 
-    (ExistingFile('tests/unit/core/python/_core/files_with_more_than_one_dot/a.b.c'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.c'),
-    (ExistingFile('tests/unit/core/python/_core/files_with_more_than_one_dot/a.b.c.d'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.c.d'),
-    (ExistingFile('tests/unit/core/python/_core/files_with_more_than_one_dot/a.b.c.d.e'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.c.d.e'),
-    (ExistingFile('tests/unit/core/python/_core/files_with_more_than_one_dot/a.b.c.d.e.f'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.c.d.e.f'),
-    (ExistingFile('tests/unit/core/python/_core/files_with_more_than_one_dot/a.b.c.d.e.f.g'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.c.d.e.f.g'),
-    (ExistingFile('tests/unit/core/python/_core/files_with_more_than_one_dot/a.b.c.d.e.f.g.h'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.c.d.e.f.g.h'),
-    (ExistingFile('tests/unit/core/python/_core/files_with_more_than_one_dot/a.b.c.d.e.f.g.h.py'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.c.d.e.f.g.h.py'),
-    (ExistingFile('tests/unit/core/python/_core/files_with_more_than_one_dot/a.b.c.d.e.f.g.py'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.c.d.e.f.g.py'),
-    (ExistingFile('tests/unit/core/python/_core/files_with_more_than_one_dot/a.b.c.d.e.f.py'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.c.d.e.f.py'),
-    (ExistingFile('tests/unit/core/python/_core/files_with_more_than_one_dot/a.b.c.d.e.py'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.c.d.e.py'),
-    (ExistingFile('tests/unit/core/python/_core/files_with_more_than_one_dot/a.b.c.d.py'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.c.d.py'),
-    (ExistingFile('tests/unit/core/python/_core/files_with_more_than_one_dot/a.b.c.py'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.c.py'),
-    (ExistingFile('tests/unit/core/python/_core/files_with_more_than_one_dot/a.b.py'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.py'),
-    (ExistingFile('tests/unit/core/python/_core/directory.with.more.than.one.dot/a.b.py'), None, InvalidNamespaceError, 'namespace identifier cannot contain more than one dot: a.b.py'),
-])
-def test_PythonModuleDocumentationGenerator_exceptions(module_path, src_directory, expected_exception, expected_exception_msg):
+@pytest.mark.parametrize(
+    'module_path,src_directory,expected_exception,expected_exception_msg',
+    [
+        (
+            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'),
+            ),
+            None,
+            InvalidNamespaceError,
+            'invalid module file name: a.b.c.d',
+        ),
+        (
+            pathlib.Path(
+                (
+                    'tests/unit/core/python/_core/i'
+                    'nvalid_module_names/a.b.c.d.e'
+                ),
+            ),
+            None,
+            InvalidNamespaceError,
+            'invalid module file name: a.b.c.d.e',
+        ),
+        (
+            pathlib.Path(
+                (
+                    'tests/unit/core/python/_core/in'
+                    'valid_module_names/a.b.c.d.e.f'
+                ),
+            ),
+            None,
+            InvalidNamespaceError,
+            'invalid module file name: a.b.c.d.e.f',
+        ),
+        (
+            pathlib.Path(
+                (
+                    'tests/unit/core/python/_core/inv'
+                    'alid_module_names/a.b.c.d.e.f.g'
+                ),
+            ),
+            None,
+            InvalidNamespaceError,
+            'invalid module file name: a.b.c.d.e.f.g',
+        ),
+        (
+            pathlib.Path(
+                (
+                    'tests/unit/core/python/_core/inva'
+                    'lid_module_names/a.b.c.d.e.f.g.h'
+                ),
+            ),
+            None,
+            InvalidNamespaceError,
+            'invalid module file name: a.b.c.d.e.f.g.h',
+        ),
+        (
+            pathlib.Path(
+                (
+                    'tests/unit/core/python/_core/inval'
+                    'id_module_names/a.b.c.d.e.f.g.h.py'
+                ),
+            ),
+            None,
+            InvalidNamespaceError,
+            'invalid module file name: a.b.c.d.e.f.g.h.py',
+        ),
+        (
+            pathlib.Path(
+                (
+                    'tests/unit/core/python/_core/inva'
+                    'lid_module_names/a.b.c.d.e.f.g.py'
+                ),
+            ),
+            None,
+            InvalidNamespaceError,
+            'invalid module file name: a.b.c.d.e.f.g.py',
+        ),
+        (
+            pathlib.Path(
+                (
+                    'tests/unit/core/python/_core/in'
+                    'lid_module_names/a.b.c.d.e.f.py'
+                ),
+            ),
+            None,
+            InvalidNamespaceError,
+            'invalid module file name: a.b.c.d.e.f.py',
+        ),
+        (
+            pathlib.Path(
+                (
+                    'tests/unit/core/python/_core/in'
+                    'valid_module_names/a.b.c.d.e.py'
+                ),
+            ),
+            None,
+            InvalidNamespaceError,
+            'invalid module file name: a.b.c.d.e.py',
+        ),
+        (
+            pathlib.Path(
+                (
+                    'tests/unit/core/python/_core/i'
+                    'nvalid_module_names/a.b.c.d.py'
+                ),
+            ),
+            None,
+            InvalidNamespaceError,
+            'invalid module file name: a.b.c.d.py',
+        ),
+        (
+            pathlib.Path(
+                ('tests/unit/core/python/_core/invalid_module_names/a.b.c.py'),
+            ),
+            None,
+            InvalidNamespaceError,
+            'invalid module file name: a.b.c.py',
+        ),
+        (
+            pathlib.Path(
+                ('tests/unit/core/python/_core/invalid_module_names/a.b.py'),
+            ),
+            None,
+            InvalidNamespaceError,
+            'invalid module file name: a.b.py',
+        ),
+        (
+            pathlib.Path(
+                (
+                    'tests/unit/core/python/_core/direc'
+                    'tory.with.more.than.one.dot/a.b.py'
+                ),
+            ),
+            None,
+            InvalidNamespaceError,
+            'invalid module file name: a.b.py',
+        ),
+    ],
+)
+def test_PythonModuleDocumentationGenerator_exceptions(
+    module_path,
+    src_directory,
+    expected_exception,
+    expected_exception_msg,
+):
     with pytest.raises(expected_exception) as exc_info:
         PythonModuleDocumentationGenerator(module_path, src_directory)
     assert str(exc_info.value) == expected_exception_msg
 
-@pytest.mark.parametrize('module_documentation_generator,expected', [
-    (PythonModuleDocumentationGenerator(ExistingFile('tests/unit/core/python/_core/test_project_dirs/pdir_2/src/pkg/module.py'), ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_2/src/'), allow_tables = True, allow_html = False), '''# Module `pkg.module`
+
+@pytest.mark.parametrize(
+    'module_documentation_generator,expected',
+    [
+        (
+            PythonModuleDocumentationGenerator(
+                pathlib.Path(
+                    (
+                        'tests/unit/core/python/_core/test_pr'
+                        'oject_dirs/pdir_2/src/pkg/module.py'
+                    ),
+                ),
+                pathlib.Path(
+                    'tests/unit/core/python/_core/test_project_dirs/pdir_2/src/'
+                ),
+                allow_tables=True,
+                allow_html=False,
+            ),
+            """# Module `pkg.module`
 
 A test module.
 
+## Function `fn`
+
+### Function signature
+
+```python
+fn(a: int, b: int = 42, c=42, d=42)
+```
+
+
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `a` | `int` | normal | -- | -- |
+| `b` | `int` | normal | `42` | -- |
+| `c` | `int` | normal | `42` | -- |
+| `d` | -- | normal | `42` | -- |
+
+
+
+
+
+
+
+### Docstring
+
+:param c:
+:type c: int
+
 ## Function `add`
 
 Adds two numbers.
@@ -76,8 +250,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. |
 
 
 
@@ -218,12 +392,54 @@ Barks.
 
 ### Docstring
 
-A dog.'''),
-
-    (PythonModuleDocumentationGenerator(ExistingFile('tests/unit/core/python/_core/test_project_dirs/pdir_2/src/pkg/module.py'), None, allow_tables = True, allow_html = False), '''# Module `module`
+A dog.""",
+        ),
+        (
+            PythonModuleDocumentationGenerator(
+                pathlib.Path(
+                    (
+                        'tests/unit/core/python/_core/test_pr'
+                        'oject_dirs/pdir_2/src/pkg/module.py'
+                    ),
+                ),
+                None,
+                allow_tables=True,
+                allow_html=False,
+            ),
+            """# Module `module`
 
 A test module.
 
+## Function `fn`
+
+### Function signature
+
+```python
+fn(a: int, b: int = 42, c=42, d=42)
+```
+
+
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `a` | `int` | normal | -- | -- |
+| `b` | `int` | normal | `42` | -- |
+| `c` | `int` | normal | `42` | -- |
+| `d` | -- | normal | `42` | -- |
+
+
+
+
+
+
+
+### Docstring
+
+:param c:
+:type c: int
+
 ## Function `add`
 
 Adds two numbers.
@@ -245,8 +461,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. |
 
 
 
@@ -387,12 +603,54 @@ Barks.
 
 ### Docstring
 
-A dog.'''),
-
-    (PythonModuleDocumentationGenerator(ExistingFile('tests/unit/core/python/_core/test_project_dirs/pdir_2/src/pkg/module.py'), None, allow_tables = True, allow_html = True), '''# Module `module`
+A dog.""",
+        ),
+        (
+            PythonModuleDocumentationGenerator(
+                pathlib.Path(
+                    (
+                        'tests/unit/core/python/_core/test_pr'
+                        'oject_dirs/pdir_2/src/pkg/module.py'
+                    ),
+                ),
+                None,
+                allow_tables=True,
+                allow_html=True,
+            ),
+            (
+                """# Module `module`
 
 A test module.
 
+## Function `fn`
+
+### Function signature
+
+```python
+fn(a: int, b: int = 42, c=42, d=42)
+```
+
+
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `a` | `int` | normal | -- | -- |
+| `b` | `int` | normal | `42` | -- |
+| `c` | `int` | normal | `42` | -- |
+| `d` | -- | normal | `42` | -- |
+
+
+
+
+
+
+
+<details><summary><h3 style="display:inline">Docstring</h3></summary>"""
+                """:param c:
+:type c: int</details>
+
 ## Function `add`
 
 Adds two numbers.
@@ -414,8 +672,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. |
 
 
 
@@ -423,7 +681,8 @@ Return type: `int | float`
 
 
 
-<details><summary><h3 style="display:inline">Docstring</h3></summary>Adds two numbers.
+<details><summary><h3 style="display:inline">Docstring</h3></summary>Adds """
+                """two numbers.
 
 :param a: The first number.
 :type a: int | float
@@ -490,7 +749,8 @@ Return type: `str`
 
 
 
-<details><summary><h5 style="display:inline">Docstring</h5></summary>Returns a greeting.
+<details><summary><h5 style="display:inline">Docstring</h5></summary>"""
+                """Returns a greeting.
 
 :return: The greeting.
 :rtype: str</details>
@@ -499,7 +759,8 @@ Return type: `str`
 
 
 
-<details><summary><h3 style="display:inline">Docstring</h3></summary>A class representing an animal.
+<details><summary><h3 style="display:inline">Docstring</h3></summary>A """
+                """class representing an animal.
 
 :param name: Its name.
 :type name: str</details>
@@ -540,18 +801,96 @@ Return type: `None`
 
 
 
-<details><summary><h5 style="display:inline">Docstring</h5></summary>Barks.</details>
+<details><summary><h5 style="display:inline">Docstring</h5></summary>Barks."""
+                """</details>
 
 
 
 
 
-<details><summary><h3 style="display:inline">Docstring</h3></summary>A dog.</details>'''),
-
-    (PythonModuleDocumentationGenerator(ExistingFile('tests/unit/core/python/_core/test_project_dirs/pdir_2/src/pkg/module.py'), None, allow_tables = False, allow_html = True), '''# Module `module`
+<details><summary><h3 style="display:inline">Docstring</h3></summary>A dog."""
+                '</details>'
+            ),
+        ),
+        (
+            PythonModuleDocumentationGenerator(
+                pathlib.Path(
+                    (
+                        'tests/unit/core/python/_core/test_pr'
+                        'oject_dirs/pdir_2/src/pkg/module.py'
+                    ),
+                ),
+                None,
+                allow_tables=False,
+                allow_html=True,
+            ),
+            (
+                """# Module `module`
 
 A test module.
 
+## Function `fn`
+
+### Function signature
+
+```python
+fn(a: int, b: int = 42, c=42, d=42)
+```
+
+
+
+### Parameters
+
+- Parameter: `a`
+
+  Type: `int`
+
+  Kind: normal
+
+  Default value: --
+
+  Description: --
+
+- Parameter: `b`
+
+  Type: `int`
+
+  Kind: normal
+
+  Default value: `42`
+
+  Description: --
+
+- Parameter: `c`
+
+  Type: `int`
+
+  Kind: normal
+
+  Default value: `42`
+
+  Description: --
+
+- Parameter: `d`
+
+  Type: --
+
+  Kind: normal
+
+  Default value: `42`
+
+  Description: --
+
+
+
+
+
+
+
+<details><summary><h3 style="display:inline">Docstring</h3></summary>"""
+                """:param c:
+:type c: int</details>
+
 ## Function `add`
 
 Adds two numbers.
@@ -597,7 +936,8 @@ Return type: `int | float`
 
 
 
-<details><summary><h3 style="display:inline">Docstring</h3></summary>Adds two numbers.
+<details><summary><h3 style="display:inline">Docstring</h3></summary>Adds """
+                """two numbers.
 
 :param a: The first number.
 :type a: int | float
@@ -685,7 +1025,8 @@ Return type: `str`
 
 
 
-<details><summary><h5 style="display:inline">Docstring</h5></summary>Returns a greeting.
+<details><summary><h5 style="display:inline">Docstring</h5></summary>"""
+                """Returns a greeting.
 
 :return: The greeting.
 :rtype: str</details>
@@ -694,7 +1035,8 @@ Return type: `str`
 
 
 
-<details><summary><h3 style="display:inline">Docstring</h3></summary>A class representing an animal.
+<details><summary><h3 style="display:inline">Docstring</h3></summary>A """
+                """class representing an animal.
 
 :param name: Its name.
 :type name: str</details>
@@ -741,18 +1083,96 @@ Return type: `None`
 
 
 
-<details><summary><h5 style="display:inline">Docstring</h5></summary>Barks.</details>
+<details><summary><h5 style="display:inline">Docstring</h5></summary>Barks."""
+                """</details>
 
 
 
 
 
-<details><summary><h3 style="display:inline">Docstring</h3></summary>A dog.</details>'''),
-
-    (PythonModuleDocumentationGenerator(ExistingFile('tests/unit/core/python/_core/test_project_dirs/pdir_2/src/pkg/module.py'), None, allow_tables = False, allow_html = False), '''# Module `module`
+<details><summary><h3 style="display:inline">Docstring</h3></summary>A """
+                'dog.</details>'
+            ),
+        ),
+        (
+            PythonModuleDocumentationGenerator(
+                pathlib.Path(
+                    (
+                        'tests/unit/core/python/_core/test_pr'
+                        'oject_dirs/pdir_2/src/pkg/module.py'
+                    ),
+                ),
+                None,
+                allow_tables=False,
+                allow_html=False,
+            ),
+            """# Module `module`
 
 A test module.
 
+## Function `fn`
+
+### Function signature
+
+```python
+fn(a: int, b: int = 42, c=42, d=42)
+```
+
+
+
+### Parameters
+
+- Parameter: `a`
+
+  Type: `int`
+
+  Kind: normal
+
+  Default value: --
+
+  Description: --
+
+- Parameter: `b`
+
+  Type: `int`
+
+  Kind: normal
+
+  Default value: `42`
+
+  Description: --
+
+- Parameter: `c`
+
+  Type: `int`
+
+  Kind: normal
+
+  Default value: `42`
+
+  Description: --
+
+- Parameter: `d`
+
+  Type: --
+
+  Kind: normal
+
+  Default value: `42`
+
+  Description: --
+
+
+
+
+
+
+
+### Docstring
+
+:param c:
+:type c: int
+
 ## Function `add`
 
 Adds two numbers.
@@ -958,7 +1378,12 @@ Barks.
 
 ### Docstring
 
-A dog.'''),
-])
-def test_PythonModuleDocumentationGenerator_exceptions(module_documentation_generator, expected):
+A dog.""",
+        ),
+    ],
+)
+def test_PythonModuleDocumentationGenerator_generate_documentation(
+    module_documentation_generator,
+    expected,
+):
     assert module_documentation_generator.generate_documentation() == expected

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

@@ -12,16 +12,21 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from src.jcloud_docsgen.core.python._core import _argument_kind_human_readable
-from src.jcloud_docsgen.core.python.arguments import PythonArgumentKind
 import pytest
 
-@pytest.mark.parametrize('argument_kind,expected', [
-    (PythonArgumentKind.NORMAL, 'normal'),
-    (PythonArgumentKind.POSITIONAL_ONLY, 'positional-only'),
-    (PythonArgumentKind.KEYWORD_ONLY, 'keyword-only'),
-    (PythonArgumentKind.VARARG, 'vararg'),
-    (PythonArgumentKind.KWARGS, 'kwargs'),
-])
+from src.jcloud_docsgen.core.python._core import _argument_kind_human_readable
+from src.jcloud_docsgen.core.python.arguments import PythonArgumentKind
+
+
+@pytest.mark.parametrize(
+    'argument_kind,expected',
+    [
+        (PythonArgumentKind.NORMAL, 'normal'),
+        (PythonArgumentKind.POSITIONAL_ONLY, 'positional-only'),
+        (PythonArgumentKind.KEYWORD_ONLY, 'keyword-only'),
+        (PythonArgumentKind.VARARG, 'vararg'),
+        (PythonArgumentKind.KWARGS, 'kwargs'),
+    ],
+)
 def test__argument_kind_human_readable(argument_kind, expected):
     assert _argument_kind_human_readable(argument_kind) == expected

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

@@ -12,15 +12,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from src.jcloud_docsgen.core.python._core import _collect_definitions
-from src.jcloud_docsgen.core.python.definitions import PythonClassDefinition, PythonFunctionDefinition
-from src.jcloud_docsgen.core.python.arguments import PythonFunctionArgument, PythonArgumentKind
-from src.jcloud_docsgen.core.python.docstrings import PythonDocstring
-import pytest
 import ast
 
+import pytest
+
+from src.jcloud_docsgen.core.python._core import _collect_definitions
+from src.jcloud_docsgen.core.python.arguments import (
+    PythonArgumentKind,
+    PythonFunctionArgument,
+)
+from src.jcloud_docsgen.core.python.definitions import (
+    PythonClassDefinition,
+    PythonFunctionDefinition,
+)
+from src.jcloud_docsgen.core.python.docstrings import PythonDocstring
+
+
 def module(source_code: str) -> ast.Module:
-    '''
+    """
     Returns an AST module of the source code.
 
     :param source_code: The module source code.
@@ -28,18 +37,41 @@ def module(source_code: str) -> ast.Module:
 
     :return: The AST module.
     :rtype: ast.Module
-    '''
+    """
 
     return ast.parse(source_code)
 
-@pytest.mark.parametrize('module,expected', [
-    (module('def add(a, b):\n\treturn a + b'), [
-        PythonFunctionDefinition('add', [
-            PythonFunctionArgument('a', PythonArgumentKind.NORMAL, None, None),
-            PythonFunctionArgument('b', PythonArgumentKind.NORMAL, None, None),
-        ], None, None, [])
-    ]),
-    (module('''def add(a: int | float, b: int | float) -> int | float:
+
+@pytest.mark.parametrize(
+    'module,expected',
+    [
+        (
+            module('def add(a, b):\n\treturn a + b'),
+            [
+                PythonFunctionDefinition(
+                    'add',
+                    [
+                        PythonFunctionArgument(
+                            'a',
+                            PythonArgumentKind.NORMAL,
+                            None,
+                            None,
+                        ),
+                        PythonFunctionArgument(
+                            'b',
+                            PythonArgumentKind.NORMAL,
+                            None,
+                            None,
+                        ),
+                    ],
+                    None,
+                    None,
+                    [],
+                ),
+            ],
+        ),
+        (
+            module('''def add(a: int | float, b: int | float) -> int | float:
     """Adds two numbers."""
     return a + b
 
@@ -49,91 +81,305 @@ class Something:
     """A class."""
     def __init__(self, value: typing.Any = 42) -> None:
             self._value = value
-            
+
     @property
     def value(self) -> typing.Any:
         """
         The value.
         """
         return self.get_value()
-            
+
     def get_value(self) -> typing.Any:
         """
         Returns the value.
         """
         return self._value
-'''), [
-        PythonFunctionDefinition('add', [
-            PythonFunctionArgument('a', PythonArgumentKind.NORMAL, None, 'int | float'),
-            PythonFunctionArgument('b', PythonArgumentKind.NORMAL, None, 'int | float'),
-        ], 'int | float', PythonDocstring('Adds two numbers.'), []),
-        PythonClassDefinition('Something', [], PythonDocstring('A class.'), [], [
-            PythonFunctionDefinition('__init__', [
-                PythonFunctionArgument('self', PythonArgumentKind.NORMAL, None, None),
-                PythonFunctionArgument('value', PythonArgumentKind.NORMAL, '42', 'typing.Any'),
-            ], 'None', None, []),
-            PythonFunctionDefinition('value', [
-                PythonFunctionArgument('self', PythonArgumentKind.NORMAL, None, None),
-            ], 'typing.Any', PythonDocstring('The value.'), ['property']),
-            PythonFunctionDefinition('get_value', [
-                PythonFunctionArgument('self', PythonArgumentKind.NORMAL, None, None),
-            ], 'typing.Any', PythonDocstring('Returns the value.'), []),
-        ])
-    ]),
-    (module('''from src.jcloud_docsgen.core.python import PythonDocumentationGenerator
-from src.jcloud_docsgen.core.python.namespaces import PythonModuleNamespace, PythonPackageNamespace
+'''),
+            [
+                PythonFunctionDefinition(
+                    'add',
+                    [
+                        PythonFunctionArgument(
+                            'a',
+                            PythonArgumentKind.NORMAL,
+                            None,
+                            'int | float',
+                        ),
+                        PythonFunctionArgument(
+                            'b',
+                            PythonArgumentKind.NORMAL,
+                            None,
+                            'int | float',
+                        ),
+                    ],
+                    'int | float',
+                    PythonDocstring('Adds two numbers.'),
+                    [],
+                ),
+                PythonClassDefinition(
+                    'Something',
+                    [],
+                    PythonDocstring('A class.'),
+                    [],
+                    [
+                        PythonFunctionDefinition(
+                            '__init__',
+                            [
+                                PythonFunctionArgument(
+                                    'self',
+                                    PythonArgumentKind.NORMAL,
+                                    None,
+                                    None,
+                                ),
+                                PythonFunctionArgument(
+                                    'value',
+                                    PythonArgumentKind.NORMAL,
+                                    '42',
+                                    'typing.Any',
+                                ),
+                            ],
+                            'None',
+                            None,
+                            [],
+                        ),
+                        PythonFunctionDefinition(
+                            'value',
+                            [
+                                PythonFunctionArgument(
+                                    'self',
+                                    PythonArgumentKind.NORMAL,
+                                    None,
+                                    None,
+                                ),
+                            ],
+                            'typing.Any',
+                            PythonDocstring('The value.'),
+                            ['property'],
+                        ),
+                        PythonFunctionDefinition(
+                            'get_value',
+                            [
+                                PythonFunctionArgument(
+                                    'self',
+                                    PythonArgumentKind.NORMAL,
+                                    None,
+                                    None,
+                                ),
+                            ],
+                            'typing.Any',
+                            PythonDocstring('Returns the value.'),
+                            [],
+                        ),
+                    ],
+                ),
+            ],
+        ),
+        (
+            module("""from src.jcloud_docsgen.core.python import (
+    PythonDocumentationGenerator
+)
+from src.jcloud_docsgen.core.python.namespaces import (
+    PythonModuleNamespace,
+    PythonPackageNamespace
+)
 import pytest
-from src.jcloud_docsgen.utils import ExistingDirectory
 
 @pytest.mark.parametrize('project_directory,docs_directory', [
     (1, 1),
     (1, None),
     (42, None),
-    (ExistingDirectory('tests'), 1),
-    (ExistingDirectory('tests/'), 1),
-    (1, ExistingDirectory('tests/')),
-    (1, ExistingDirectory('tests')),
-    (None, ExistingDirectory('tests')),
+    (pathlib.Path('tests'), 1),
+    (pathlib.Path('tests/'), 1),
+    (1, pathlib.Path('tests/')),
+    (1, pathlib.Path('tests')),
+    (None, pathlib.Path('tests')),
 ])
-def test_PythonDocumentationGenerator_type_exceptions(project_directory, docs_directory):
+def test_PythonDocumentationGenerator_type_exceptions(
+    project_directory,
+    docs_directory
+):
     with pytest.raises(TypeError):
         PythonDocumentationGenerator(project_directory, docs_directory)
 
 @pytest.mark.parametrize('python_documentation_generator,expected', [
-    (PythonDocumentationGenerator(ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_1'), ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_1/docs')), []),
-    (PythonDocumentationGenerator(ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_2'), ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_2/docs')), [PythonPackageNamespace('pkg', [PythonModuleNamespace('module')])]),
-    (PythonDocumentationGenerator(ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_3'), ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_3/docs')), [PythonPackageNamespace('pkg', [PythonModuleNamespace('module'), PythonPackageNamespace('pkg', [PythonModuleNamespace('module2')])])]),
+    (PythonDocumentationGenerator(
+        pathlib.Path(
+            'tests/unit/core/python/_core/test_project_dirs/pdir_1'
+        ),
+        pathlib.Path(
+            'tests/unit/core/python/_core/test_project_dirs/pdir_1/docs'
+        )
+    ), []),
+    (PythonDocumentationGenerator(
+        pathlib.Path(
+            'tests/unit/core/python/_core/test_project_dirs/pdir_2'
+        ),
+        pathlib.Path(
+            'tests/unit/core/python/_core/test_project_dirs/pdir_2/docs'
+        )
+    ), [PythonPackageNamespace('pkg', [PythonModuleNamespace('module')])]),
+    (PythonDocumentationGenerator(
+        pathlib.Path(
+            'tests/unit/core/python/_core/test_project_dirs/pdir_3'
+        ),
+        pathlib.Path(
+            'tests/unit/core/python/_core/test_project_dirs/pdir_3/docs'
+        )
+    ), [
+        PythonPackageNamespace(
+            'pkg',
+            [
+                PythonModuleNamespace('module'),
+                PythonPackageNamespace('pkg',
+                    [PythonModuleNamespace('module2')]
+                )
+            ]
+        )
+    ])
 ])
-def test_PythonDocumentationGenerator_collect_modules(python_documentation_generator: PythonDocumentationGenerator, expected):
-    assert python_documentation_generator.namespace() == expected'''), [
-        PythonFunctionDefinition('test_PythonDocumentationGenerator_type_exceptions', [
-            PythonFunctionArgument('project_directory', PythonArgumentKind.NORMAL, None, None),
-            PythonFunctionArgument('docs_directory', PythonArgumentKind.NORMAL, None, None),
-        ], None, None, ['''pytest.mark.parametrize('project_directory,docs_directory', [(1, 1), (1, None), (42, None), (ExistingDirectory('tests'), 1), (ExistingDirectory('tests/'), 1), (1, ExistingDirectory('tests/')), (1, ExistingDirectory('tests')), (None, ExistingDirectory('tests'))])''']),
-        PythonFunctionDefinition('test_PythonDocumentationGenerator_collect_modules', [
-            PythonFunctionArgument('python_documentation_generator', PythonArgumentKind.NORMAL, None, 'PythonDocumentationGenerator'),
-            PythonFunctionArgument('expected', PythonArgumentKind.NORMAL, None, None)
-        ], None, None, ['''pytest.mark.parametrize('python_documentation_generator,expected', [(PythonDocumentationGenerator(ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_1'), ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_1/docs')), []), (PythonDocumentationGenerator(ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_2'), ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_2/docs')), [PythonPackageNamespace('pkg', [PythonModuleNamespace('module')])]), (PythonDocumentationGenerator(ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_3'), ExistingDirectory('tests/unit/core/python/_core/test_project_dirs/pdir_3/docs')), [PythonPackageNamespace('pkg', [PythonModuleNamespace('module'), PythonPackageNamespace('pkg', [PythonModuleNamespace('module2')])])])])'''])
-    ]),
-    (module('''class C1:
+def test_PythonDocumentationGenerator_collect_modules(
+    python_documentation_generator: PythonDocumentationGenerator,
+    expected
+):
+    assert python_documentation_generator.namespace() == expected"""),
+            [
+                PythonFunctionDefinition(
+                    'test_PythonDocumentationGenerator_type_exceptions',
+                    [
+                        PythonFunctionArgument(
+                            'project_directory',
+                            PythonArgumentKind.NORMAL,
+                            None,
+                            None,
+                        ),
+                        PythonFunctionArgument(
+                            'docs_directory',
+                            PythonArgumentKind.NORMAL,
+                            None,
+                            None,
+                        ),
+                    ],
+                    None,
+                    None,
+                    [
+                        (
+                            """pytest.mark.parametrize('project_directo"""
+                            """ry,docs_directory', [(1, 1), (1, None), """
+                            """(42, None), (pathlib.Path('tests'), 1), """
+                            """(pathlib.Path('tests/'), 1), (1, pathlib"""
+                            """.Path('tests/')), (1, pathlib.Path('test"""
+                            """s')), (None, pathlib.Path('tests'))])"""
+                        ),
+                    ],
+                ),
+                PythonFunctionDefinition(
+                    'test_PythonDocumentationGenerator_collect_modules',
+                    [
+                        PythonFunctionArgument(
+                            'python_documentation_generator',
+                            PythonArgumentKind.NORMAL,
+                            None,
+                            'PythonDocumentationGenerator',
+                        ),
+                        PythonFunctionArgument(
+                            'expected',
+                            PythonArgumentKind.NORMAL,
+                            None,
+                            None,
+                        ),
+                    ],
+                    None,
+                    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')])])])])"
+                        )
+                    ],
+                ),
+            ],
+        ),
+        (
+            module(
+                """class C1:
     class C2:
         class C3:
             def function(self, value: bool, /, arg) -> bool:
                 def should_be_not_in_the_result(arg: int) -> object:
                     pass
-                return not value'''), [
-                    PythonClassDefinition('C1', [], None, [], [
-                        PythonClassDefinition('C2', [], None, [], [
-                            PythonClassDefinition('C3', [], None, [], [
-                                PythonFunctionDefinition('function', [
-                                    PythonFunctionArgument('self', PythonArgumentKind.POSITIONAL_ONLY, None, None),
-                                    PythonFunctionArgument('value', PythonArgumentKind.POSITIONAL_ONLY, None, 'bool'),
-                                    PythonFunctionArgument('arg', PythonArgumentKind.NORMAL, None, None),
-                                ], 'bool', None, [])
-                            ])
-                        ])
-                    ])
-                ])
-])
+                return not value"""
+            ),
+            [
+                PythonClassDefinition(
+                    'C1',
+                    [],
+                    None,
+                    [],
+                    [
+                        PythonClassDefinition(
+                            'C2',
+                            [],
+                            None,
+                            [],
+                            [
+                                PythonClassDefinition(
+                                    'C3',
+                                    [],
+                                    None,
+                                    [],
+                                    [
+                                        PythonFunctionDefinition(
+                                            'function',
+                                            [
+                                                PythonFunctionArgument(
+                                                    'self',
+                                                    PythonArgumentKind.POSITIONAL_ONLY,
+                                                    None,
+                                                    None,
+                                                ),
+                                                PythonFunctionArgument(
+                                                    'value',
+                                                    PythonArgumentKind.POSITIONAL_ONLY,
+                                                    None,
+                                                    'bool',
+                                                ),
+                                                PythonFunctionArgument(
+                                                    'arg',
+                                                    PythonArgumentKind.NORMAL,
+                                                    None,
+                                                    None,
+                                                ),
+                                            ],
+                                            'bool',
+                                            None,
+                                            [],
+                                        ),
+                                    ],
+                                ),
+                            ],
+                        ),
+                    ],
+                ),
+            ],
+        ),
+    ],
+)
 def test___collect_definitions(module, expected):
     assert list(_collect_definitions(module)) == expected

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

@@ -1,56 +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.
-
-from src.jcloud_docsgen.core.python._core import _fit_row_length
-import pytest
-
-@pytest.mark.parametrize('expected_length,row,expected', [
-    (0, (), ()),
-    (1, (), (None,)),
-    (2, (), (None, None)),
-    (2, (1,), (1, None)),
-
-    (0, (1,), ()),
-    (1, (1, 2), (1,)),
-    (1, (1, 2), (1,)),
-    (0, (1, 2), ()),
-    (0, (1, 2, 3), ()),
-    (1, (1, 2, 3), (1,)),
-    (2, (1, 2, 3), (1, 2)),
-
-    (1, (1,), (1,)),
-    (2, (1, 1), (1, 1)),
-    (2, (1, 2), (1, 2)),
-    (3, (1, 2, 3), (1, 2, 3)),
-])
-def test__fit_row_length(expected_length, row, expected):
-    assert _fit_row_length(expected_length, row) == expected
-
-@pytest.mark.parametrize('row', [
-    (),
-    (1,),
-    (1, 2),
-    (1, 2, 3),
-    (1, 2, 3, 456),
-])
-@pytest.mark.parametrize('expected_length,expected_exception', [
-    (-1, ValueError),
-    (-2, ValueError),
-    (-3, ValueError),
-    (-42, ValueError),
-])
-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)
-    assert str(exc_info.value) == 'expected must be larger than or equal 0.'

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

@@ -12,13 +12,23 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from src.jcloud_docsgen.core.python._core import _function_params_info, _FunctionParamInfo
-from src.jcloud_docsgen.core.python.arguments import PythonFunctionArgument, PythonArgumentKind
-import pytest
 import docstring_parser
+import pytest
 
-def docstring_args_list(docstring: str) -> list[docstring_parser.DocstringParam]:
-    '''
+from src.jcloud_docsgen.core.python._core import (
+    _function_params_info,
+    _FunctionParamInfo,
+)
+from src.jcloud_docsgen.core.python.arguments import (
+    PythonArgumentKind,
+    PythonFunctionArgument,
+)
+
+
+def docstring_args_list(
+    docstring: str,
+) -> list[docstring_parser.DocstringParam]:
+    """
     Returns the parameter list of a docstring.
 
     :param docstring: The docstring
@@ -26,79 +36,164 @@ def docstring_args_list(docstring: str) -> list[docstring_parser.DocstringParam]
 
     :return: The parameter list.
     :rtype: list[docstring_parser.DocstringParam]
-    '''
+    """
 
     return docstring_parser.parse(docstring).params
 
-@pytest.mark.parametrize('arg_list,docstring,expected', [
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, '', 'int'),
-    ], ':param a: a\n:type a: str', {
-        'a': _FunctionParamInfo('int', 'a')
-    }),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, '', None),
-    ], ':param a: a\n:type a: str', {
-        'a': _FunctionParamInfo('str', 'a')
-    }),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, '', None),
-        PythonFunctionArgument('b', PythonArgumentKind.NORMAL, '', None),
-    ], ':param a: a\n:type a: str', {
-        'a': _FunctionParamInfo('str', 'a'),
-        'b': _FunctionParamInfo(None, None)
-    }),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, '', None),
-        PythonFunctionArgument('b', PythonArgumentKind.NORMAL, '', 'int'),
-    ], ':param a: a\n:type a: str', {
-        'a': _FunctionParamInfo('str', 'a'),
-        'b': _FunctionParamInfo('int', None)
-    }),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, '', None),
-        PythonFunctionArgument('b', PythonArgumentKind.NORMAL, '', 'int'),
-    ], ':param a: a\n:type a: str\n:param b: b\n:type b: str', {
-        'a': _FunctionParamInfo('str', 'a'),
-        'b': _FunctionParamInfo('int', 'b')
-    }),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, '', None),
-    ], ':param a: a\n:type a: str\n:param b: b\n:type b: int', {
-        'a': _FunctionParamInfo('str', 'a')
-    }),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, '', None),
-    ], '', {
-        'a': _FunctionParamInfo(None, None)
-    }),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, '', 'str'),
-    ], '', {
-        'a': _FunctionParamInfo('str', None)
-    }),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, '', 'str'),
-    ], ':param a:\n:type a: int', {
-        'a': _FunctionParamInfo('str', '')
-    }),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, '', None),
-    ], ':param a:\n:type a: int', {
-        'a': _FunctionParamInfo('int', '')
-    }),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, '', None),
-    ], ':param a: a', {
-        'a': _FunctionParamInfo(None, 'a')
-    }),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, '', 'str'),
-    ], ':param a: a', {
-        'a': _FunctionParamInfo('str', 'a')
-    }),
-    ([], ':param a: a\n:type a: str', {}),
-    ([], '', {}),
-])
+
+@pytest.mark.parametrize(
+    'arg_list,docstring,expected',
+    [
+        (
+            [
+                PythonFunctionArgument(
+                    'a', PythonArgumentKind.NORMAL, '', 'int'
+                ),
+            ],
+            ':param a: a\n:type a: str',
+            {
+                'a': _FunctionParamInfo('int', 'a'),
+            },
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a', PythonArgumentKind.NORMAL, '', None
+                ),
+            ],
+            ':param a: a\n:type a: str',
+            {
+                'a': _FunctionParamInfo('str', 'a'),
+            },
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a', PythonArgumentKind.NORMAL, '', None
+                ),
+                PythonFunctionArgument(
+                    'b', PythonArgumentKind.NORMAL, '', None
+                ),
+            ],
+            ':param a: a\n:type a: str',
+            {
+                'a': _FunctionParamInfo('str', 'a'),
+                'b': _FunctionParamInfo(None, None),
+            },
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a', PythonArgumentKind.NORMAL, '', None
+                ),
+                PythonFunctionArgument(
+                    'b', PythonArgumentKind.NORMAL, '', 'int'
+                ),
+            ],
+            ':param a: a\n:type a: str',
+            {
+                'a': _FunctionParamInfo('str', 'a'),
+                'b': _FunctionParamInfo('int', None),
+            },
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a', PythonArgumentKind.NORMAL, '', None
+                ),
+                PythonFunctionArgument(
+                    'b', PythonArgumentKind.NORMAL, '', 'int'
+                ),
+            ],
+            ':param a: a\n:type a: str\n:param b: b\n:type b: str',
+            {
+                'a': _FunctionParamInfo('str', 'a'),
+                'b': _FunctionParamInfo('int', 'b'),
+            },
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a', PythonArgumentKind.NORMAL, '', None
+                ),
+            ],
+            ':param a: a\n:type a: str\n:param b: b\n:type b: int',
+            {
+                'a': _FunctionParamInfo('str', 'a'),
+            },
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a', PythonArgumentKind.NORMAL, '', None
+                ),
+            ],
+            '',
+            {
+                'a': _FunctionParamInfo(None, None),
+            },
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a', PythonArgumentKind.NORMAL, '', 'str'
+                ),
+            ],
+            '',
+            {
+                'a': _FunctionParamInfo('str', None),
+            },
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a', PythonArgumentKind.NORMAL, '', 'str'
+                ),
+            ],
+            ':param a:\n:type a: int',
+            {
+                'a': _FunctionParamInfo('str', ''),
+            },
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a', PythonArgumentKind.NORMAL, '', None
+                ),
+            ],
+            ':param a:\n:type a: int',
+            {
+                'a': _FunctionParamInfo('int', ''),
+            },
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a', PythonArgumentKind.NORMAL, '', None
+                ),
+            ],
+            ':param a: a',
+            {
+                'a': _FunctionParamInfo(None, 'a'),
+            },
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a', PythonArgumentKind.NORMAL, '', 'str'
+                ),
+            ],
+            ':param a: a',
+            {
+                'a': _FunctionParamInfo('str', 'a'),
+            },
+        ),
+        ([], ':param a: a\n:type a: str', {}),
+        ([], '', {}),
+    ],
+)
 def test__function_params_types(arg_list, docstring, expected):
-    assert _function_params_info(arg_list, docstring_args_list(docstring)) == expected
+    assert (
+        _function_params_info(arg_list, docstring_args_list(docstring))
+        == expected
+    )

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

@@ -1,93 +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.
-
-from src.jcloud_docsgen.core.python._core import _markdown_table
-import pytest
-
-@pytest.mark.parametrize('header,body,allow_markdown_table,force_row_lengths,one_line_values,missing_value,expected', [
-    ([], [], False, False, True, '--', ''),
-    ([], [('a',)], False, False, True, '--', ''),
-    (['a'], [], False, False, True, '--', ''),
-    (['a'], [(1,)], True, False, True, '--', '''| a |
-| --- |
-| 1 |'''),
-    (['a'], [(1, 2)], True, False, True, '--', '''| a |
-| --- |
-| 1 |'''),
-    (['a', 'b'], [(1, 2)], True, False, True, '--', '''| a | b |
-| --- | --- |
-| 1 | 2 |'''),
-    (['a', 'b'], [(1,)], True, False, True, '--', '''| a | b |
-| --- | --- |
-| 1 | -- |'''),
-    (['a', 'b'], [()], True, False, True, '--', '''| a | b |
-| --- | --- |
-| -- | -- |'''),
-    (['a', 'b'], [(1, 2), (3, 4)], True, False, True, '--', '''| a | b |
-| --- | --- |
-| 1 | 2 |
-| 3 | 4 |'''),
-    (['a'], [('line1\nline2',)], True, False, True, '--', '''| a |
-| --- |
-| line1 line2 |'''),
-    (['a'], [('line1\nline2',)], True, False, False, '--', '''| a |
-| --- |
-| line1\nline2 |'''),
-
-    ([], [], False, False, True, '--', ''),
-    ([], [('a',)], False, False, True, '--', ''),
-    (['a'], [], False, False, True, '--', ''),
-    (['a'], [(1,)], False, False, True, '--', '''- a: 1'''),
-    (['a'], [(1, 2)], False, False, True, '--', '''- a: 1'''),
-    (['a', 'b'], [(1, 2)], False, False, True, '--', '''- a: 1
-
-  b: 2'''),
-    (['a', 'b'], [(1,)], False, False, True, '--', '''- a: 1
-
-  b: --'''),
-    (['a', 'b'], [()], False, False, True, '--', '''- a: --
-
-  b: --'''),
-    (['a', 'b'], [(1, 2), (3, 4)], False, False, True, '--', '''- a: 1
-
-  b: 2
-
-- a: 3
-
-  b: 4'''),
-    (['a'], [('line1\nline2',)], False, False, True, '--', '- a: line1 line2'),
-    (['a'], [('line1\nline2',)], False, False, False, '--', '- a: line1\nline2'),
-])
-def test__markdown_table(header, body, allow_markdown_table, force_row_lengths, one_line_values, missing_value, expected):
-    assert _markdown_table(header, body, allow_markdown_table = allow_markdown_table, force_row_lengths = force_row_lengths, one_line_values = one_line_values, missing_value = missing_value) == expected
-
-@pytest.mark.parametrize('header,body,allow_markdown_table,force_row_lengths,one_line_values,missing_value,expected_exception,expected_exception_msg', [
-    (['a'], [(1, 2)], True, True, True, '--', ValueError, 'expected 1 value, got 2'),
-    (['a'], [(1, 2, 3)], True, True, True, '--', ValueError, 'expected 1 value, got 3'),
-    (['a'], [()], True, True, True, '--', ValueError, 'expected 1 value, got 0'),
-    (['a', 'b'], [()], True, True, True, '--', ValueError, 'expected 2 values, got 0'),
-    (['a', 'b'], [(1,)], True, True, True, '--', ValueError, 'expected 2 values, got 1'),
-    (['a', 'b'], [(1, 2, 3)], True, True, True, '--', ValueError, 'expected 2 values, got 3'),
-
-    (['a'], [(1, 2)], False, True, True, '--', ValueError, 'expected 1 value, got 2'),
-    (['a'], [(1, 2, 3)], False, True, True, '--', ValueError, 'expected 1 value, got 3'),
-    (['a'], [()], False, True, True, '--', ValueError, 'expected 1 value, got 0'),
-    (['a', 'b'], [()], False, True, True, '--', ValueError, 'expected 2 values, got 0'),
-    (['a', 'b'], [(1,)], False, True, True, '--', ValueError, 'expected 2 values, got 1'),
-    (['a', 'b'], [(1, 2, 3)], False, True, True, '--', ValueError, 'expected 2 values, got 3'),
-])
-def test__markdown_table_exceptions(header, body, allow_markdown_table, force_row_lengths, one_line_values, missing_value, expected_exception, expected_exception_msg):
-    with pytest.raises(expected_exception) as exc_info:
-        _markdown_table(header, body, allow_markdown_table = allow_markdown_table, force_row_lengths = force_row_lengths, one_line_values = one_line_values, missing_value = missing_value)
-    assert str(exc_info.value) == expected_exception_msg

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

@@ -12,86 +12,347 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from src.jcloud_docsgen.core.python._core import _signature_argument_list
-from src.jcloud_docsgen.core.python.arguments import PythonFunctionArgument, PythonArgumentKind
 import pytest
 
-@pytest.mark.parametrize('argument_list,expected', [
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, None, None)
-    ], ['a']),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.POSITIONAL_ONLY, None, None)
-    ], ['a', '/']),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.POSITIONAL_ONLY, None, None),
-        PythonFunctionArgument('b', PythonArgumentKind.NORMAL, None, None),
-    ], ['a', '/', 'b']),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.POSITIONAL_ONLY, None, None),
-        PythonFunctionArgument('b', PythonArgumentKind.NORMAL, None, None),
-        PythonFunctionArgument('c', PythonArgumentKind.KEYWORD_ONLY, None, None),
-    ], ['a', '/', 'b', '*', 'c']),
-    ([
-        PythonFunctionArgument('b', PythonArgumentKind.NORMAL, None, None),
-        PythonFunctionArgument('c', PythonArgumentKind.KEYWORD_ONLY, None, None),
-    ], ['b', '*', 'c']),
-    ([
-        PythonFunctionArgument('c', PythonArgumentKind.KEYWORD_ONLY, None, None),
-    ], ['*', 'c']),
-    ([
-        PythonFunctionArgument('b', PythonArgumentKind.POSITIONAL_ONLY, None, None),
-        PythonFunctionArgument('c', PythonArgumentKind.KEYWORD_ONLY, None, None),
-    ], ['b', '/', '*', 'c']),
-    ([
-        PythonFunctionArgument('args', PythonArgumentKind.VARARG, None, None),
-    ], ['*args']),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, None, None),
-        PythonFunctionArgument('args', PythonArgumentKind.VARARG, None, None),
-    ], ['a', '*args']),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.POSITIONAL_ONLY, None, None),
-        PythonFunctionArgument('args', PythonArgumentKind.VARARG, None, None),
-    ], ['a', '/', '*args']),
-    ([
-        PythonFunctionArgument('args', PythonArgumentKind.VARARG, None, None),
-        PythonFunctionArgument('a', PythonArgumentKind.KEYWORD_ONLY, None, None),
-    ], ['*args', 'a']),
-    ([
-        PythonFunctionArgument('args', PythonArgumentKind.VARARG, None, None),
-        PythonFunctionArgument('kwargs', PythonArgumentKind.KWARGS, None, None),
-    ], ['*args', '**kwargs']),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.POSITIONAL_ONLY, None, None),
-        PythonFunctionArgument('args', PythonArgumentKind.VARARG, None, None),
-        PythonFunctionArgument('kwargs', PythonArgumentKind.KWARGS, None, None),
-    ], ['a', '/', '*args', '**kwargs']),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, None, None),
-        PythonFunctionArgument('args', PythonArgumentKind.VARARG, None, None),
-        PythonFunctionArgument('kwargs', PythonArgumentKind.KWARGS, None, None),
-    ], ['a', '*args', '**kwargs']),
-    ([
-        PythonFunctionArgument('args', PythonArgumentKind.VARARG, None, None),
-        PythonFunctionArgument('a', PythonArgumentKind.KEYWORD_ONLY, None, None),
-        PythonFunctionArgument('kwargs', PythonArgumentKind.KWARGS, None, None),
-    ], ['*args', 'a', '**kwargs']),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.KEYWORD_ONLY, None, None),
-        PythonFunctionArgument('kwargs', PythonArgumentKind.KWARGS, None, None),
-    ], ['*', 'a', '**kwargs']),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, None, None),
-        PythonFunctionArgument('kwargs', PythonArgumentKind.KWARGS, None, None),
-    ], ['a', '**kwargs']),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.POSITIONAL_ONLY, None, None),
-        PythonFunctionArgument('kwargs', PythonArgumentKind.KWARGS, None, None),
-    ], ['a', '/', '**kwargs']),
-    ([
-        PythonFunctionArgument('a', PythonArgumentKind.NORMAL, '1', 'int'),
-    ], ['a: int = 1']),
-])
+from src.jcloud_docsgen.core.python._core import _signature_argument_list
+from src.jcloud_docsgen.core.python.arguments import (
+    PythonArgumentKind,
+    PythonFunctionArgument,
+)
+
+
+@pytest.mark.parametrize(
+    'argument_list,expected',
+    [
+        (
+            [
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.NORMAL,
+                    None,
+                    None,
+                ),
+            ],
+            ['a'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.POSITIONAL_ONLY,
+                    None,
+                    None,
+                ),
+            ],
+            ['a', '/'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.POSITIONAL_ONLY,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'b',
+                    PythonArgumentKind.NORMAL,
+                    None,
+                    None,
+                ),
+            ],
+            ['a', '/', 'b'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.POSITIONAL_ONLY,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'b',
+                    PythonArgumentKind.NORMAL,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'c',
+                    PythonArgumentKind.KEYWORD_ONLY,
+                    None,
+                    None,
+                ),
+            ],
+            ['a', '/', 'b', '*', 'c'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'b',
+                    PythonArgumentKind.NORMAL,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'c',
+                    PythonArgumentKind.KEYWORD_ONLY,
+                    None,
+                    None,
+                ),
+            ],
+            ['b', '*', 'c'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'c',
+                    PythonArgumentKind.KEYWORD_ONLY,
+                    None,
+                    None,
+                ),
+            ],
+            ['*', 'c'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'b',
+                    PythonArgumentKind.POSITIONAL_ONLY,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'c',
+                    PythonArgumentKind.KEYWORD_ONLY,
+                    None,
+                    None,
+                ),
+            ],
+            ['b', '/', '*', 'c'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'args',
+                    PythonArgumentKind.VARARG,
+                    None,
+                    None,
+                )
+            ],
+            ['*args'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.NORMAL,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'args',
+                    PythonArgumentKind.VARARG,
+                    None,
+                    None,
+                ),
+            ],
+            ['a', '*args'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.POSITIONAL_ONLY,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'args',
+                    PythonArgumentKind.VARARG,
+                    None,
+                    None,
+                ),
+            ],
+            ['a', '/', '*args'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'args',
+                    PythonArgumentKind.VARARG,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.KEYWORD_ONLY,
+                    None,
+                    None,
+                ),
+            ],
+            ['*args', 'a'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'args',
+                    PythonArgumentKind.VARARG,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'kwargs',
+                    PythonArgumentKind.KWARGS,
+                    None,
+                    None,
+                ),
+            ],
+            ['*args', '**kwargs'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.POSITIONAL_ONLY,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'args',
+                    PythonArgumentKind.VARARG,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'kwargs',
+                    PythonArgumentKind.KWARGS,
+                    None,
+                    None,
+                ),
+            ],
+            ['a', '/', '*args', '**kwargs'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.NORMAL,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'args',
+                    PythonArgumentKind.VARARG,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'kwargs',
+                    PythonArgumentKind.KWARGS,
+                    None,
+                    None,
+                ),
+            ],
+            ['a', '*args', '**kwargs'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'args',
+                    PythonArgumentKind.VARARG,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.KEYWORD_ONLY,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'kwargs',
+                    PythonArgumentKind.KWARGS,
+                    None,
+                    None,
+                ),
+            ],
+            ['*args', 'a', '**kwargs'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.KEYWORD_ONLY,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'kwargs',
+                    PythonArgumentKind.KWARGS,
+                    None,
+                    None,
+                ),
+            ],
+            ['*', 'a', '**kwargs'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.NORMAL,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'kwargs',
+                    PythonArgumentKind.KWARGS,
+                    None,
+                    None,
+                ),
+            ],
+            ['a', '**kwargs'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.POSITIONAL_ONLY,
+                    None,
+                    None,
+                ),
+                PythonFunctionArgument(
+                    'kwargs',
+                    PythonArgumentKind.KWARGS,
+                    None,
+                    None,
+                ),
+            ],
+            ['a', '/', '**kwargs'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.NORMAL,
+                    '1',
+                    'int',
+                ),
+            ],
+            ['a: int = 1'],
+        ),
+        (
+            [
+                PythonFunctionArgument(
+                    'a',
+                    PythonArgumentKind.NORMAL,
+                    '1',
+                    None,
+                ),
+            ],
+            ['a=1'],
+        ),
+    ],
+)
 def test__signature_argument_list(argument_list, expected):
     assert _signature_argument_list(argument_list) == expected

tests/unit/core/python/_core/test_project_dirs/pdir_2/src/pkg/module.py

@@ -1,9 +1,17 @@
-'''
+"""
 A test module.
-'''
+"""
+
+
+def fn(a: int, b: int = 42, c=42, d=42):
+    """
+    :param c:
+    :type c: int
+    """
+
 
 def add(a: int | float, b: int | float) -> int | float:
-    '''
+    """
     Adds two numbers.
 
     :param a: The first number.
@@ -13,38 +21,41 @@ def add(a: int | float, b: int | float) -> int | float:
 
     :return: The sum.
     :rtype: int | float
-    '''
+    """
 
     return a + b
 
+
 class Animal:
-    '''
+    """
     A class representing an animal.
 
     :param name: Its name.
     :type name: str
-    '''
+    """
+
     def __init__(self, name: str) -> None:
         self.name = name
 
     def greet(self):
-        '''
+        """
         Returns a greeting.
 
         :return: The greeting.
         :rtype: str
-        '''
+        """
 
         return f'Hi there! My name is {self.name}'
 
+
 class Dog(Animal):
-    '''
+    """
     A dog.
-    '''
+    """
 
     def bark(self) -> None:
-        '''
+        """
         Barks.
-        '''
+        """
 
         print('Woof!')