Merge pull request 'Chore: prepare 0.2.2' (#69) from chore/prepare-0-2-2 into main

Reviewed-on: #69

.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

.gitea/workflows/release.yml

@@ -0,0 +1,120 @@
+# 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: Release package
+
+on:
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build package
+    runs-on: python
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build package
+        run: |
+          python3 -m build
+        
+      - name: Upload artifact
+        uses: christopherhx/gitea-upload-artifact@v4
+        with:
+          name: build-output
+          path: |
+            dist/*.tar.gz
+            dist/*.whl
+
+  prepare_upload_release_asset:
+    name: Prepare release asset upload
+    runs-on: debian
+    needs: build
+
+    outputs:
+      files: ${{ steps.files.outputs.files }}
+
+    steps:
+      - name: Download artifact
+        uses: christopherhx/gitea-download-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+
+      - id: files
+        shell: bash
+        run: |
+          files=$(node --input-type=module -e '
+          import { glob } from "node:fs/promises";
+
+          const files = await Array.fromAsync(glob([
+            "dist/*.tar.gz",
+            "dist/*.whl"
+          ]));
+
+          console.log(JSON.stringify(files));
+          ')
+
+          echo "files=$files" >> "$GITHUB_OUTPUT"
+
+  upload_release_asset:
+    name: Upload release asset
+    runs-on: debian
+    needs: [build, prepare_upload_release_asset]
+
+    strategy:
+      matrix:
+        file: ${{ fromJSON(needs.prepare_upload_release_asset.outputs.files) }}
+
+    steps:
+      - name: Download artifact
+        uses: christopherhx/gitea-download-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+
+      - uses: ${{ gitea.server_url }}/jCloud/actions/upload-release-asset@60d1ae076c2e1802e4bc9461e26c42c557652811
+        with:
+          file: ${{ matrix.file }}
+          release: ${{ gitea.event.release.id }}
+        env:
+          GITEA_TOKEN: ${{ secrets.RELEASE_ASSET_TOKEN }}
+
+  publish:
+    if: ${{ !github.event.release.prerelease && !github.event.release.draft }}
+    name: Publish package to package registry
+    runs-on: python
+    needs: build
+  
+    steps:
+      - name: Download artifact
+        uses: christopherhx/gitea-download-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+      
+      - name: Upload package
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          python3 -m twine upload \
+            --repository-url ${{ gitea.server_url }}/api/packages/${{ gitea.repository_owner }}/pypi \
+            --disable-progress-bar \
+            dist/*

.gitignore

@@ -1,5 +1,177 @@
-dist/
+# Byte-compiled / optimized / DLL files
-src/*.egg-info/
-.vscode/
-.pytest_cache/
 __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.

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2026 jCloud Services GbR
+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.

README.md

@@ -0,0 +1,22 @@
+# jcloud-docsgen
+
+A tool that generates Markdown documentation from software project source code.
+
+Currently supported programming languages:
+- Python
+
+## Installation
+
+You can install the package `jcloud-docsgen` from the [Gitea Package Registry](https://gitea.jcloud-services.ddns.net/jCloud/-/packages/pypi/jcloud-docsgen/).
+
+## Setup
+
+Please execute `scripts/setup.sh` when cloning the repository to configure Git.
+
+## Reference
+
+API reference and generated documentation can be found in [docs/reference](docs/reference).
+
+## Notice
+
+This project is under active development. The documentation will be expanded over time.

docs/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## [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
+
+- utility class for existing directories
+- utility class for existing files
+- Python project documentation generator
+- Python definition documentation generator
+- Python module documentation generator
+- Python namespaces
+- signature representation of a Python function argument
+- Python docstrings

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/arguments.md

@@ -0,0 +1,205 @@
+# Module `jcloud_docsgen.core.python.arguments`
+
+## Class `PythonArgumentKind`
+
+### Base classes
+
+- `Enum`
+
+## Class `PythonFunctionArgument`
+
+Represents an argument of a Python function.
+
+
+
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, name: str, kind: PythonArgumentKind, default: str | None, annotation: str | None) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `name` | `str` | normal | -- | -- |
+| `kind` | `PythonArgumentKind` | normal | -- | -- |
+| `default` | `str | None` | normal | -- | -- |
+| `annotation` | `str | None` | normal | -- | -- |
+
+#### Method `__eq__`
+
+##### Method signature
+
+```python
+__eq__(self, value: PythonFunctionArgument) -> bool
+```
+
+##### Returns
+
+Return type: `bool`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `value` | `PythonFunctionArgument` | normal | -- | -- |
+
+#### Method `__repr__`
+
+##### Method signature
+
+```python
+__repr__(self) -> str
+```
+
+##### Returns
+
+Return type: `str`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+#### Method `signature_repr`
+
+Returns the function signature representation of the argument.
+
+
+##### Method signature
+
+```python
+signature_repr(self) -> str
+```
+
+##### Returns
+
+The string representation of the argument.
+
+Return type: `str`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+
+
+
+
+
+
+##### Docstring
+
+Returns the function signature representation of the argument.
+
+:return: The string representation of the argument.
+:rtype: str
+
+
+
+
+
+### Docstring
+
+Represents an argument of a Python function.
+
+:param name: The name of the argument.
+:type name: str
+:param kind: The kind of the argument.
+:type kind: ArgumentKind
+:param default: The default value of the argument.
+:type default: str | None
+:param annotation: The type annotation of the argument.
+:type annotation: str | None
+
+## Class `PythonASTArgumentsListParser`
+
+A parser for making ``PythonFunctionArgument`` objects from an
+``ast.arguments`` arguments list.
+
+
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, ast_arguments_list: ast.arguments) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `ast_arguments_list` | `ast.arguments` | normal | -- | -- |
+
+#### Method `to_argument_list`
+
+Converts the AST arguments list to a list of Python function
+argument objects.
+
+##### Method signature
+
+```python
+to_argument_list(self) -> list[PythonFunctionArgument]
+```
+
+##### Returns
+
+The list of Python function argument objects.
+
+Return type: `list[PythonFunctionArgument]`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+
+
+
+
+
+
+##### Docstring
+
+Converts the AST arguments list to a list of Python function
+argument objects.
+
+:return: The list of Python function argument objects.
+:rtype: list[PythonFunctionArgument]
+
+
+
+
+
+### Docstring
+
+A parser for making ``PythonFunctionArgument`` objects from an
+``ast.arguments`` arguments list.
+
+:param ast_arguments_list: The ``ast.arguments`` arguments list.
+:type ast_arguments_list: ast.arguments

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

@@ -0,0 +1,445 @@
+# Module `jcloud_docsgen.core.python.definitions`
+
+## Function `_python_docstring`
+
+Returns the PythonDocstring object if the docstring is a string and
+not ``None``.
+
+### Function signature
+
+```python
+_python_docstring(doc: str | None) -> PythonDocstring | None
+```
+
+### Returns
+
+The PythonDocstring object or ``None``.
+
+Return type: `PythonDocstring | None`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `doc` | `str | None` | normal | -- | The docstring. |
+
+
+
+
+
+
+
+### Docstring
+
+Returns the PythonDocstring object if the docstring is a string and
+not ``None``.
+
+:param doc: The docstring.
+:type doc: str | None
+
+:return: The PythonDocstring object or ``None``.
+:rtype: PythonDocstring | None
+
+## Class `PythonDefinition`
+
+A base class for Python definition (a class, function or asynchronous
+function definition) classes.
+
+
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, name: str, doc: PythonDocstring | None, decorators: list[str]) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `name` | `str` | normal | -- | -- |
+| `doc` | `PythonDocstring | None` | normal | -- | -- |
+| `decorators` | `list[str]` | normal | -- | -- |
+
+#### Method `_arg_list`
+
+##### Method signature
+
+```python
+_arg_list(self) -> tuple
+```
+
+##### Returns
+
+Return type: `tuple`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+#### Method `__repr__`
+
+##### Method signature
+
+```python
+__repr__(self) -> str
+```
+
+##### Returns
+
+Return type: `str`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+#### Method `from_node`
+
+From an AST node.
+
+
+##### Method signature
+
+```python
+from_node(cls, node: ast.stmt) -> PythonDefinition
+```
+
+##### Returns
+
+Return type: `PythonDefinition`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `cls` | -- | normal | -- | -- |
+| `node` | `ast.stmt` | normal | -- | The AST node. |
+
+
+
+##### Decorators
+
+```python
+classmethod
+```
+
+
+
+##### Docstring
+
+From an AST node.
+
+:param node: The AST node.
+:type node: ast.stmt
+
+#### Method `__eq__`
+
+##### Method signature
+
+```python
+__eq__(self, value: object) -> bool
+```
+
+##### Returns
+
+Return type: `bool`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `value` | `object` | normal | -- | -- |
+
+
+
+
+
+### Docstring
+
+A base class for Python definition (a class, function or asynchronous
+function definition) classes.
+
+:param name: The name of the definition.
+:type name: str
+:param doc: The docstring.
+:type doc: PythonDocstring | None
+:param decorators: The definition decorators.
+:type decorators: list[str]
+
+:raises InvalidPythonIdentifierError: If the name is not a valid
+                                      Python identifier.
+
+## Class `PythonFunctionDefinition`
+
+A PythonDefinition subclass representing a Python function
+definition.
+
+### Base classes
+
+- `PythonDefinition`
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, name: str, args: list[PythonFunctionArgument], returns: str | None, doc: PythonDocstring | None, decorators: list[str]) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `name` | `str` | normal | -- | -- |
+| `args` | `list[PythonFunctionArgument]` | normal | -- | -- |
+| `returns` | `str | None` | normal | -- | -- |
+| `doc` | `PythonDocstring | None` | normal | -- | -- |
+| `decorators` | `list[str]` | normal | -- | -- |
+
+#### Method `_arg_list`
+
+##### Method signature
+
+```python
+_arg_list(self) -> tuple
+```
+
+##### Returns
+
+Return type: `tuple`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+#### Method `from_node`
+
+From an AST node.
+
+
+##### Method signature
+
+```python
+from_node(cls, node: ast.stmt) -> PythonFunctionDefinition
+```
+
+##### Returns
+
+Return type: `PythonFunctionDefinition`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `cls` | -- | normal | -- | -- |
+| `node` | `ast.stmt` | normal | -- | The AST node. |
+
+
+
+##### Decorators
+
+```python
+classmethod
+```
+
+
+
+##### Docstring
+
+From an AST node.
+
+:param node: The AST node.
+:type node: ast.stmt
+
+
+
+
+
+### Docstring
+
+A PythonDefinition subclass representing a Python function
+definition.
+
+:param name: The name of the definition.
+:type name: str
+:param args: The arguments.
+:type args: list[PythonFunctionArgument]
+:param returns: The return type of the function or class.
+:type returns: str | None
+:param doc: The docstring.
+: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 `PythonAsyncFunctionDefinition`
+
+A PythonDefinition subclass representing an asynchronous Python function
+definition.
+
+### Base classes
+
+- `PythonFunctionDefinition`
+
+
+
+
+
+
+
+### Docstring
+
+A PythonDefinition subclass representing an asynchronous Python function
+definition.
+
+:param name: The name of the definition.
+:type name: str
+:param args: The arguments.
+:type args: list[PythonFunctionArgument]
+:param returns: The return type of the function or class.
+:type returns: str | None
+:param doc: The docstring.
+: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`
+
+A PythonDefinition subclass representing a Python class definition.
+
+
+### Base classes
+
+- `PythonDefinition`
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, name: str, bases: list[str], doc: PythonDocstring | None, decorators: list[str], body: list[PythonDefinition]) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `name` | `str` | normal | -- | -- |
+| `bases` | `list[str]` | normal | -- | -- |
+| `doc` | `PythonDocstring | None` | normal | -- | -- |
+| `decorators` | `list[str]` | normal | -- | -- |
+| `body` | `list[PythonDefinition]` | normal | -- | -- |
+
+#### Method `_arg_list`
+
+##### Method signature
+
+```python
+_arg_list(self) -> tuple
+```
+
+##### Returns
+
+Return type: `tuple`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+#### Method `from_node`
+
+From an AST node.
+
+
+##### Method signature
+
+```python
+from_node(cls, node: ast.stmt) -> PythonClassDefinition
+```
+
+##### Returns
+
+Return type: `PythonClassDefinition`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `cls` | -- | normal | -- | -- |
+| `node` | `ast.stmt` | normal | -- | The AST node. |
+
+
+
+##### Decorators
+
+```python
+classmethod
+```
+
+
+
+##### Docstring
+
+From an AST node.
+
+:param node: The AST node.
+:type node: ast.stmt
+
+
+
+
+
+### Docstring
+
+A PythonDefinition subclass representing a Python class definition.
+
+:param name: The name of the definition.
+:type name: str
+:param bases: The base classes.
+:type bases: list[str]
+:param doc: The docstring.
+:type doc: PythonDocstring | None
+:param decorators: The definition decorators.
+:type decorators: list[str]
+:param body:
+:type body: list[PythonDefinition]
+
+:raises InvalidPythonIdentifierError: If the name is not a valid
+                                      Python identifier.

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

@@ -0,0 +1,113 @@
+# Module `jcloud_docsgen.core.python.docstrings`
+
+## Class `PythonDocstring`
+
+Represents a Python docstring.
+
+
+
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, docstring: str) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `docstring` | `str` | normal | -- | -- |
+
+#### Method `__repr__`
+
+##### Method signature
+
+```python
+__repr__(self) -> str
+```
+
+##### Returns
+
+Return type: `str`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+#### Method `__eq__`
+
+##### Method signature
+
+```python
+__eq__(self, value) -> bool
+```
+
+##### Returns
+
+Return type: `bool`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `value` | -- | normal | -- | -- |
+
+#### Method `parse`
+
+Parses the docstring.
+
+
+##### Method signature
+
+```python
+parse(self) -> docstring_parser.Docstring
+```
+
+##### Returns
+
+The parsed docstring.
+
+Return type: `docstring_parser.Docstring`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+
+
+
+
+
+
+##### Docstring
+
+Parses the docstring.
+
+:return: The parsed docstring.
+:rtype: docstring_parser.Docstring
+
+
+
+
+
+### Docstring
+
+Represents a Python docstring.
+
+:param docstring: The docstring as a string.
+:type docstring: str

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

@@ -0,0 +1,486 @@
+# 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.
+
+
+
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, name: str) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `name` | `str` | normal | -- | -- |
+
+#### Method `__repr__`
+
+##### Method signature
+
+```python
+__repr__(self) -> str
+```
+
+##### Returns
+
+Return type: `str`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+
+
+
+
+### Docstring
+
+The base class for all Python namespaces such as modules or packages.
+
+:param name: The name of the namespace.
+:type name: str
+
+:raises InvalidNamespaceError: If the namespace  name is invalid.
+
+## Class `PythonPackageNamespace`
+
+A subclass of ``PythonNamespace`` for Python package namespaces.
+
+
+### Base classes
+
+- `PythonNamespace`
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, name: str, sub_namespaces: list[PythonNamespace]) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `name` | `str` | normal | -- | -- |
+| `sub_namespaces` | `list[PythonNamespace]` | normal | -- | -- |
+
+#### Method `namespace`
+
+Returns the namespace object with a specific identifier, such as
+``['package', 'subpackage', 'module']``.
+
+##### Method signature
+
+```python
+namespace(self, sub_namespaces: list[str]) -> PythonNamespace
+```
+
+##### Returns
+
+The namespace.
+
+Return type: `PythonNamespace`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `sub_namespaces` | `list[str]` | normal | -- | The identifier of the namespace. |
+
+##### Exceptions
+
+| Exception | Description |
+| --- | --- |
+| `InvalidNamespaceError` | If the namespace identifier is invalid. |
+| `NamespaceNotFoundError` | If the namespace does not exist. |
+
+
+
+
+
+##### Docstring
+
+Returns the namespace object with a specific identifier, such as
+``['package', 'subpackage', 'module']``.
+
+:param sub_namespaces: The identifier of the namespace.
+:type sub_namespaces: list[str]
+
+:raises InvalidNamespaceError: If the namespace identifier is
+                               invalid.
+:raises NamespaceNotFoundError: If the namespace does not exist.
+
+:return: The namespace.
+:rtype: PythonNamespace
+
+#### Method `_sub_namespaces_names`
+
+Returns the names of all sub-namespaces of the specified package
+namespace and keeps the package structure.
+
+##### Method signature
+
+```python
+_sub_namespaces_names(self, package: PythonPackageNamespace) -> PythonPackageNamespaceDictType
+```
+
+##### Returns
+
+The names if all sub-namespaces.
+
+Return type: `PythonPackageNamespaceDictType`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `package` | `PythonPackageNamespace` | normal | -- | The package. |
+
+
+
+
+
+
+
+##### Docstring
+
+Returns the names of all sub-namespaces of the specified package
+namespace and keeps the package structure.
+
+:param package: The package.
+:type package: PythonPackageNamespace
+
+:return: The names if all sub-namespaces.
+:rtype: PythonPackageNamespaceDictType
+
+#### Method `sub_namespace_names`
+
+Returns the names of all sub-namespaces and keeps the package
+structure.
+
+##### Method signature
+
+```python
+sub_namespace_names(self) -> PythonPackageNamespaceDictType
+```
+
+##### Returns
+
+The names if all sub-namespaces.
+
+Return type: `PythonPackageNamespaceDictType`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+
+
+
+
+
+
+##### Docstring
+
+Returns the names of all sub-namespaces and keeps the package
+structure.
+
+:return: The names if all sub-namespaces.
+:rtype: PythonPackageNamespaceDictType
+
+#### Method `__eq__`
+
+##### Method signature
+
+```python
+__eq__(self, value: PythonPackageNamespace) -> bool
+```
+
+##### Returns
+
+Return type: `bool`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `value` | `PythonPackageNamespace` | normal | -- | -- |
+
+#### Method `__repr__`
+
+##### Method signature
+
+```python
+__repr__(self) -> str
+```
+
+##### Returns
+
+Return type: `str`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+#### Method `__getitem__`
+
+Returns a namespace with the specified name.
+
+
+##### Method signature
+
+```python
+__getitem__(self, name: str) -> PythonNamespace
+```
+
+##### Returns
+
+The namespace
+
+Return type: `PythonNamespace`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `name` | `str` | normal | -- | The name of the namespace |
+
+##### Exceptions
+
+| Exception | Description |
+| --- | --- |
+| `NamespaceNotFoundError` | If the namespace does not exist. |
+
+
+
+
+
+##### Docstring
+
+Returns a namespace with the specified name.
+
+:param name: The name of the namespace
+:type name: str
+
+:raises NamespaceNotFoundError: If the namespace does not exist.
+
+:return: The namespace
+:rtype: PythonNamespace
+
+#### Method `add`
+
+Adds a namespace.
+
+
+##### Method signature
+
+```python
+add(self, namespace: PythonNamespace) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `namespace` | `PythonNamespace` | normal | -- | The namespace to add. |
+
+##### Exceptions
+
+| Exception | Description |
+| --- | --- |
+| `NamespaceExistsError` | If a namespace with the name of the namespace that is attempted to add already exists. |
+
+
+
+
+
+##### Docstring
+
+Adds a namespace.
+
+:param namespace: The namespace to add.
+:type namespace: PythonNamespace
+
+:raises NamespaceExistsError: If a namespace with the name of the
+                              namespace that is attempted to add
+                              already exists.
+
+#### Method `sub_namespaces`
+
+##### Method signature
+
+```python
+sub_namespaces(self) -> list[PythonNamespace]
+```
+
+##### Returns
+
+Return type: `list[PythonNamespace]`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+
+
+##### Decorators
+
+```python
+property
+```
+
+
+
+
+
+### Docstring
+
+A subclass of ``PythonNamespace`` for Python package namespaces.
+
+:param name: The name of the namespace.
+:type name: str
+:param sub_namespaces: The sub-namespaces.
+:type sub_namespaces: list[PythonNamespace]
+
+:raises InvalidNamespaceError: If the namespace name is invalid.
+
+## Class `PythonModuleNamespace`
+
+A subclass of ``PythonNamespace`` for Python module namespaces.
+
+
+### Base classes
+
+- `PythonNamespace`
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, name: str) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `name` | `str` | normal | -- | -- |
+
+#### Method `__eq__`
+
+##### Method signature
+
+```python
+__eq__(self, value: PythonModuleNamespace) -> bool
+```
+
+##### Returns
+
+Return type: `bool`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `value` | `PythonModuleNamespace` | normal | -- | -- |
+
+
+
+
+
+### Docstring
+
+A subclass of ``PythonNamespace`` for Python module namespaces.
+
+:param name: The name of the namespace.
+:type name: str

docs/reference/jcloud_docsgen/exceptions.md

@@ -0,0 +1,290 @@
+# Module `jcloud_docsgen.exceptions`
+
+## Class `NamespaceError`
+
+Base class for namespace errors.
+
+### Base classes
+
+- `ValueError`
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, *args: object, namespace_identifier: str = '') -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `args` | `object` | vararg | -- | -- |
+| `namespace_identifier` | `str` | keyword-only | `''` | -- |
+
+#### Method `__str__`
+
+##### Method signature
+
+```python
+__str__(self)
+```
+
+
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+
+
+
+
+### Docstring
+
+Base class for namespace errors.
+
+## Class `InvalidNamespaceError`
+
+### Base classes
+
+- `NamespaceError`
+
+## Class `NamespaceNotFoundError`
+
+### Base classes
+
+- `NamespaceError`
+
+## Class `NamespaceExistsError`
+
+### Base classes
+
+- `NamespaceError`
+
+## Class `PythonIdentifierError`
+
+Base class for Python identifier errors.
+
+### Base classes
+
+- `ValueError`
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, *args: object, identifier: str = '') -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `args` | `object` | vararg | -- | -- |
+| `identifier` | `str` | keyword-only | `''` | -- |
+
+#### Method `__str__`
+
+##### Method signature
+
+```python
+__str__(self)
+```
+
+
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+
+
+
+
+### Docstring
+
+Base class for Python identifier errors.
+
+## Class `InvalidPythonIdentifierError`
+
+### Base classes
+
+- `PythonIdentifierError`
+
+## Class `PythonAnnotationError`
+
+Base class for Python annotation errors.
+
+### Base classes
+
+- `ValueError`
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, *args: object, annotation: str = '') -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `args` | `object` | vararg | -- | -- |
+| `annotation` | `str` | keyword-only | `''` | -- |
+
+#### Method `__str__`
+
+##### Method signature
+
+```python
+__str__(self)
+```
+
+
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+
+
+
+
+### Docstring
+
+Base class for Python annotation errors.
+
+## Class `InvalidPythonAnnotationError`
+
+### Base classes
+
+- `PythonAnnotationError`
+
+## Class `PythonDefinitionError`
+
+Base class for Python definition errors.
+
+### Base classes
+
+- `ValueError`
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, *args: object, definition: str = '') -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `args` | `object` | vararg | -- | -- |
+| `definition` | `str` | keyword-only | `''` | -- |
+
+#### Method `__str__`
+
+##### Method signature
+
+```python
+__str__(self)
+```
+
+
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+
+
+
+
+### Docstring
+
+Base class for Python definition errors.
+
+## Class `PythonArgumentStructureError`
+
+### Base classes
+
+- `PythonDefinitionError`
+
+## 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

@@ -0,0 +1,343 @@
+# Module `jcloud_docsgen.utils`
+
+The utilities for jcloud_docsgen
+
+## Class `ExistingDirectory`
+
+pathlib.Path subclass that is a directory.
+
+ExistingDirectory represents a filesystem path but it also checks
+whether the path exists and is not a file but a directory. It
+inherits from pathlib.Path.
+
+### Base classes
+
+- `pathlib.Path`
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, path, *args, **kwargs) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `path` | -- | normal | -- | -- |
+| `args` | -- | vararg | -- | -- |
+| `kwargs` | -- | kwargs | -- | -- |
+
+### Decorators
+
+```python
+deprecated('Use pathlib.Path instead.')
+```
+
+
+
+### Docstring
+
+pathlib.Path subclass that is a directory.
+
+ExistingDirectory represents a filesystem path but it also checks
+whether the path exists and is not a file but a directory. It
+inherits from pathlib.Path.
+
+## Class `ExistingFile`
+
+pathlib.Path subclass that is a file.
+
+ExistingFile represents a filesystem path but it also checks whether
+the path exists and is not a directory but a file. It inherits from
+pathlib.Path.
+
+### Base classes
+
+- `pathlib.Path`
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, path, *args, **kwargs) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `path` | -- | normal | -- | -- |
+| `args` | -- | vararg | -- | -- |
+| `kwargs` | -- | kwargs | -- | -- |
+
+### Decorators
+
+```python
+deprecated('Use pathlib.Path instead.')
+```
+
+
+
+### Docstring
+
+pathlib.Path subclass that is a file.
+
+ExistingFile represents a filesystem path but it also checks whether
+the path exists and is not a directory but a file. It inherits from
+pathlib.Path.
+
+## Function `_quote`
+
+Quotes a string.
+
+
+### Function signature
+
+```python
+_quote(string: str, quotation_mark: str) -> str
+```
+
+### Returns
+
+The quoted string
+
+Return type: `str`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `string` | `str` | normal | -- | The string to quote |
+| `quotation_mark` | `str` | normal | -- | The quotation mark |
+
+
+
+
+
+
+
+### Docstring
+
+Quotes a string.
+
+:param string: The string to quote
+:type string: str
+:param quotation_mark: The quotation mark
+:type quotation_mark: str
+
+:return: The quoted string
+:rtype: str
+
+## Function `human_readable_list`
+
+Generates a human-readable list from a list.
+
+
+### Function signature
+
+```python
+human_readable_list(ls: list, final_separator: str = 'and', quotation_mark: str = '') -> str
+```
+
+### Returns
+
+The human-readable list.
+
+Return type: `str`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `ls` | `list` | normal | -- | The list. |
+| `final_separator` | `str` | normal | `'and'` | The seperator between the last and the second-to-last element of the list. Default is 'and'. |
+| `quotation_mark` | `str` | normal | `''` | The characters that are inserted before and after an element. Default is ''. |
+
+
+
+
+
+
+
+### Docstring
+
+Generates a human-readable list from a list.
+
+:param ls: The list.
+:type ls: list
+:param final_separator: The seperator between the last and the
+                        second-to-last element of the list. Default
+                        is 'and'.
+:type final_separator: str
+:param quotation_mark: The characters that are inserted before and
+                       after an element. Default is ''.
+
+:return: The human-readable list.
+:rtype: str
+
+## Function `_list_type_names`
+
+Converts a list of types into a list of their names (``__name__``
+attribute)
+
+### Function signature
+
+```python
+_list_type_names(types: list[type]) -> list[str]
+```
+
+### Returns
+
+The list of the names of the types
+
+Return type: `list[str]`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `types` | `list[type]` | normal | -- | The list of types |
+
+
+
+
+
+
+
+### Docstring
+
+Converts a list of types into a list of their names (``__name__``
+attribute)
+
+:param types: The list of types
+:type types: list[type]
+
+:return: The list of the names of the types
+:rtype: list[str]
+
+## Function `assert_that_is_instance`
+
+### Function signature
+
+```python
+assert_that_is_instance(obj: object, class_or_tuple: type | types.UnionType | tuple[type, ...]) -> None
+```
+
+### Returns
+
+Return type: `None`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `obj` | `object` | normal | -- | -- |
+| `class_or_tuple` | `type | types.UnionType | tuple[type, ...]` | normal | -- | -- |
+
+## Function `non_empty_str`
+
+Returns the value or ``None``.
+
+Returns the value if it is not empty and not `Ǹone``; otherwise,
+returns ``None``.
+Please note: values are stripped, i. e. if the value consists only
+             of spaces, it is also considered empty.
+
+### Function signature
+
+```python
+non_empty_str(value: str | None) -> str | None
+```
+
+### Returns
+
+The value or ``None``.
+
+Return type: `str | None`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `str | None` | normal | -- | The value. |
+
+
+
+
+
+
+
+### Docstring
+
+Returns the value or ``None``.
+
+Returns the value if it is not empty and not `Ǹone``; otherwise,
+returns ``None``.
+Please note: values are stripped, i. e. if the value consists only
+             of spaces, it is also considered empty.
+
+:param value: The value.
+:type value: str | None
+
+:return: The value or ``None``.
+:rtype: str | None
+
+## Function `get_relative_path_segments`
+
+Returns the path segments relative to ``root``.
+
+
+### Function signature
+
+```python
+get_relative_path_segments(path: pathlib.Path, root: pathlib.Path) -> list[str]
+```
+
+### Returns
+
+The path segments relative to ``root``.
+
+Return type: `list[str]`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `path` | `pathlib.Path` | normal | -- | The path. |
+| `root` | `pathlib.Path` | normal | -- | The root path. |
+
+
+
+
+
+
+
+### Docstring
+
+Returns the path segments relative to ``root``.
+
+:param path: The path.
+:type path: pathlib.Path
+:param root: The root path.
+:type root: pathlib.Path
+
+:return: The path segments relative to ``root``.
+:rtype: list[str]

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

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "jcloud-docsgen"
+version = "0.2.2"
+description = "A tool that generates Markdown documentation for software project source code"
+dependencies = ["docstring-parser", "typing-extensions (>=4.16.0,<5.0.0)"]
+requires-python = ">=3.10"
+license = "Apache-2.0"
+
+[project.scripts]
+jcloud-docsgen = "jcloud_docsgen.cli:main"
+
+[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

@@ -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
+from .core import *  # noqa: F403
+from .core import __all__ as _core__all__
+
+__all__ = [
+    'cli',
+    *_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/__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

@@ -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/core/python/__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 namespaces
+from ._core import *  # noqa: F403
+from ._core import __all__ as _core__all__
+
+__all__ = [
+    *_core__all__,
+    'namespaces',
+]

src/jcloud_docsgen/core/python/arguments.py

@@ -0,0 +1,295 @@
+# 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 __future__ import annotations
+
+import ast
+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',
+]
+
+
+class PythonArgumentKind(Enum):
+    NORMAL = 0
+    POSITIONAL_ONLY = 1
+    KEYWORD_ONLY = 2
+    VARARG = 3
+    KWARGS = 4
+
+
+class PythonFunctionArgument:
+    """
+    Represents an argument of a Python function.
+
+    :param name: The name of the argument.
+    :type name: str
+    :param kind: The kind of the argument.
+    :type kind: ArgumentKind
+    :param default: The default value of the argument.
+    :type default: str | None
+    :param annotation: The type annotation of the argument.
+    :type annotation: str | 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))
+        assert_that_is_instance(annotation, (str, types.NoneType))
+
+        # check whether name is a valid identifier
+        if not name or not name.isidentifier() or keyword.iskeyword(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,
+            )
+
+        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(),
+            )
+
+    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
+        )
+
+    def __repr__(self) -> str:
+        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 = '**'
+        elif self.kind == PythonArgumentKind.VARARG:
+            str_repr = '*'
+        else:
+            str_repr = ''
+
+        str_repr += self.name
+
+        if self.annotation is not None:
+            str_repr += ': ' + self.annotation
+
+        if self.default is not None:
+            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:
+        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
+            ]
+        )
+
+        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,
+                    ),
+                )
+            else:
+                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,
+                    ),
+                )
+            else:
+                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,
+                    ),
+                )
+            else:
+                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,
+                    ),
+                )
+            else:
+                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,
+                    ),
+                )
+            else:
+                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

@@ -0,0 +1,259 @@
+# 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 __future__ import annotations
+
+import ast
+import keyword
+import types
+
+from ...exceptions import InvalidPythonIdentifierError
+from ...utils import assert_that_is_instance
+from .arguments import PythonASTArgumentsListParser, PythonFunctionArgument
+from .docstrings import PythonDocstring
+
+__all__ = [
+    'PythonDefinition',
+    'PythonFunctionDefinition',
+    'PythonAsyncFunctionDefinition',
+    'PythonClassDefinition',
+]
+
+
+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: str | None
+
+    :return: The PythonDocstring object or ``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: 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: PythonDocstring | None,
+        decorators: list[str],
+    ) -> None:
+        if keyword.iskeyword(name) or not name.isidentifier() or not name:
+            raise InvalidPythonIdentifierError(
+                'invalid identifier',
+                identifier=name,
+            )
+
+        assert_that_is_instance(doc, (PythonDocstring, types.NoneType))
+
+        self.name = name
+        self.doc = doc
+        self.decorators = decorators
+
+    def _arg_list(self) -> tuple:
+        return (
+            self.name,
+            self.doc,
+            self.decorators,
+        )
+
+    def __repr__(self) -> str:
+        return type(self).__name__ + repr(self._arg_list())
+
+    @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],
+        )
+
+    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.
+
+    :param name: The name of the definition.
+    :type name: str
+    :param args: The arguments.
+    :type args: list[PythonFunctionArgument]
+    :param returns: The return type of the function or class.
+    :type returns: str | None
+    :param doc: The docstring.
+    :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: str | None,
+        doc: PythonDocstring | None,
+        decorators: list[str],
+    ) -> None:
+        super().__init__(name, doc, decorators)
+        self.args = args
+        self.returns = returns
+
+    def _arg_list(self) -> tuple:
+        return (
+            self.name,
+            self.args,
+            self.returns,
+            self.doc,
+            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],
+        )
+
+
+class PythonAsyncFunctionDefinition(PythonFunctionDefinition):
+    """
+    A PythonDefinition subclass representing an asynchronous Python function
+    definition.
+
+    :param name: The name of the definition.
+    :type name: str
+    :param args: The arguments.
+    :type args: list[PythonFunctionArgument]
+    :param returns: The return type of the function or class.
+    :type returns: str | None
+    :param doc: The docstring.
+    :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.
+    :type name: str
+    :param bases: The base classes.
+    :type bases: list[str]
+    :param doc: The docstring.
+    :type doc: PythonDocstring | None
+    :param decorators: The definition decorators.
+    :type decorators: list[str]
+    :param body:
+    :type body: list[PythonDefinition]
+
+    :raises InvalidPythonIdentifierError: If the name is not a valid
+                                          Python identifier.
+    """
+
+    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
+
+    def _arg_list(self) -> tuple:
+        return (
+            self.name,
+            self.bases,
+            self.doc,
+            self.decorators,
+            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,
+            [ast.unparse(b) for b in node.bases],
+            _python_docstring(ast.get_docstring(node)),
+            [ast.unparse(d) for d in node.decorator_list],
+            [
+                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)
+                )
+            ],
+        )

src/jcloud_docsgen/core/python/docstrings.py

@@ -0,0 +1,47 @@
+# 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 docstring_parser
+
+__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

@@ -0,0 +1,249 @@
+# 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 __future__ import annotations
+
+import keyword
+from typing import TypeAlias, Union
+
+from ...exceptions import (
+    InvalidNamespaceError,
+    NamespaceExistsError,
+    NamespaceNotFoundError,
+)
+from ...utils import assert_that_is_instance
+
+__all__ = [
+    'validate_namespace_name',
+    'PythonNamespace',
+    'PythonPackageNamespace',
+    'PythonModuleNamespace',
+]
+
+
+def validate_namespace_name(name: str) -> bool:
+    """
+    Checks whether a namespace name is valid. Namespace names are valid
+    if they contain no dots and are valid Python identifiers.
+
+    :param name: The namespace name to validate.
+    :type name: str
+
+    :returns: Whether the namespace name is valid.
+    :rtype: bool
+    """
+
+    if not isinstance(name, str):
+        return False
+
+    return name.isidentifier() and not keyword.iskeyword(name)
+
+
+class PythonNamespace:
+    """
+    The base class for all Python namespaces such as modules or packages.
+
+    :param name: The name of the namespace.
+    :type name: str
+
+    :raises InvalidNamespaceError: If the namespace  name is invalid.
+    """
+
+    def __init__(self, name: str) -> None:
+        assert_that_is_instance(name, str)
+
+        if not validate_namespace_name(name):
+            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',
+    ],
+]
+
+
+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]
+
+    :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:
+        """
+        Returns the namespace object with a specific identifier, such as
+        ``['package', 'subpackage', 'module']``.
+
+        :param sub_namespaces: The identifier of the namespace.
+        :type sub_namespaces: list[str]
+
+        :raises InvalidNamespaceError: If the namespace identifier is
+                                       invalid.
+        :raises NamespaceNotFoundError: If the namespace does not exist.
+
+        :return: The namespace.
+        :rtype: PythonNamespace
+        """
+
+        if not sub_namespaces:
+            raise InvalidNamespaceError('invalid namespace')
+
+        for sn in sub_namespaces:
+            if not sn:
+                raise InvalidNamespaceError('invalid namespace')
+
+        sub_namespace = self.__getitem__(sub_namespaces[0])
+
+        # package namespace
+        if isinstance(sub_namespace, PythonPackageNamespace):
+            if len(sub_namespaces) == 1:
+                return sub_namespace
+            return sub_namespace.namespace(sub_namespaces[1:])
+        # module namespace
+        else:
+            return sub_namespace
+
+    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
+            )
+            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)
+
+    def __eq__(self, value: PythonPackageNamespace) -> bool:
+        # For performance reasons, is not called self.sub_namespace_names
+        # if the name attribute does not match, which can be quickly
+        # verified
+        if not (isinstance(value, type(self)) and self.name == value.name):
+            return False
+
+        return value.sub_namespace_names() == self.sub_namespace_names()
+
+    def __repr__(self) -> str:
+        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
+        :type name: str
+
+        :raises NamespaceNotFoundError: If the namespace does not exist.
+
+        :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,
+        )
+
+    def add(self, namespace: PythonNamespace) -> None:
+        """
+        Adds a namespace.
+
+        :param namespace: The namespace to add.
+        :type namespace: PythonNamespace
+
+        :raises NamespaceExistsError: If a namespace with the name of the
+                                      namespace that is attempted to add
+                                      already exists.
+        """
+        try:
+            self.__getitem__(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]:
+        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 isinstance(value, type(self)) and self.name == value.name

src/jcloud_docsgen/exceptions.py

@@ -0,0 +1,136 @@
+# 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 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
+
+    def __str__(self):
+        if not self.args:
+            return ''
+        else:
+            return (
+                self.args[0]
+                + (': ' if self.namespace_identifier and self.args[0] else '')
+                + (self.namespace_identifier if self.args[0] else '')
+            )
+
+
+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
+
+    def __str__(self):
+        if not self.args:
+            return ''
+        else:
+            return (
+                self.args[0]
+                + (': ' if self.identifier and self.args[0] else '')
+                + (self.identifier if self.args[0] else '')
+            )
+
+
+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
+
+    def __str__(self):
+        if not self.args:
+            return ''
+        else:
+            return (
+                self.args[0]
+                + (': ' if self.annotation and self.args[0] else '')
+                + (self.annotation if self.args[0] else '')
+            )
+
+
+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
+
+    def __str__(self):
+        if not self.args:
+            return ''
+        else:
+            return (
+                self.args[0]
+                + (': ' if self.definition and self.args[0] else '')
+                + (self.definition if self.args[0] else '')
+            )
+
+
+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

@@ -0,0 +1,239 @@
+# 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 utilities for jcloud_docsgen
+"""
+
+import errno
+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',
+]
+
+
+@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,
+            )
+        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,
+            )
+        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
+    :type quotation_mark: 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:
+    """
+    Generates a human-readable list from a list.
+
+    :param ls: The list.
+    :type ls: list
+    :param final_separator: The seperator between the last and the
+                            second-to-last element of the list. Default
+                            is 'and'.
+    :type final_separator: str
+    :param quotation_mark: The characters that are inserted before and
+                           after an element. Default is ''.
+
+    :return: The human-readable list.
+    :rtype: str
+    """
+
+    # 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)
+    )
+
+
+def _list_type_names(types: list[type]) -> list[str]:
+    """
+    Converts a list of types into a list of their names (``__name__``
+    attribute)
+
+    :param types: The list of types
+    :type types: list[type]
+
+    :return: The list of the names of the types
+    :rtype: list[str]
+    """
+
+    return [tp.__name__ for tp in types]
+
+
+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):
+                class_or_tuple = class_or_tuple.__args__
+            if len(class_or_tuple) > 1:
+                exception_message_expected = 'either '
+            else:
+                exception_message_expected = ''
+            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}'
+            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,
+    returns ``None``.
+    Please note: values are stripped, i. e. if the value consists only
+                 of spaces, it is also considered empty.
+
+    :param value: The value.
+    :type value: str | None
+
+    :return: The value or ``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]:
+    """
+    Returns the path segments relative to ``root``.
+
+    :param path: The path.
+    :type path: pathlib.Path
+    :param root: The root path.
+    :type root: pathlib.Path
+
+    :return: The path segments relative to ``root``.
+    :rtype: list[str]
+    """
+
+    return list(
+        path.resolve()
+        .relative_to(
+            root.resolve(),
+        )
+        .parts,
+    )

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

@@ -0,0 +1,196 @@
+# 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 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(
+    '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'
+                ),
+            ),
+            [],
+        ),
+        (
+            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

@@ -0,0 +1,39 @@
+# Module `pkg.module`
+
+## Function `func`
+
+### Function signature
+
+```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/case03/expected/user_management/exceptions.md

@@ -0,0 +1,37 @@
+# Module `user_management.exceptions`
+
+## Class `UserNotFoundError`
+
+User does not exist.
+
+### Base classes
+
+- `Exception`
+
+
+
+
+
+
+
+### Docstring
+
+User does not exist.
+
+## Class `InvalidEmailError`
+
+Email address is invalid.
+
+### Base classes
+
+- `Exception`
+
+
+
+
+
+
+
+### Docstring
+
+Email address is invalid.

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

@@ -0,0 +1,21 @@
+# Module `user_management.models`
+
+## Class `User`
+
+Represents a user.
+
+
+
+
+
+### Decorators
+
+```python
+dataclass
+```
+
+
+
+### Docstring
+
+Represents a user.

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

@@ -0,0 +1,130 @@
+# Module `user_management.service`
+
+## Class `UserService`
+
+Central class for the user management.
+
+
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, storage: InMemoryUserStorage)
+```
+
+
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `storage` | `InMemoryUserStorage` | normal | -- | -- |
+
+#### Method `create_user`
+
+Creates and stores a new user.
+
+##### Method signature
+
+```python
+create_user(self, user_id: str, name: str, email: str, age: int | None = None) -> User
+```
+
+##### Returns
+
+Return type: `User`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `user_id` | `str` | normal | -- | -- |
+| `name` | `str` | normal | -- | -- |
+| `email` | `str` | normal | -- | -- |
+| `age` | `int | None` | normal | `None` | -- |
+
+
+
+
+
+
+
+##### Docstring
+
+Creates and stores a new user.
+
+#### Method `get_user`
+
+Returns a user.
+
+##### Method signature
+
+```python
+get_user(self, user_id: str) -> User
+```
+
+##### Returns
+
+Return type: `User`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `user_id` | `str` | normal | -- | -- |
+
+
+
+
+
+
+
+##### Docstring
+
+Returns a user.
+
+#### Method `delete_user`
+
+Deletes a user.
+
+##### Method signature
+
+```python
+delete_user(self, user_id: str) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `user_id` | `str` | normal | -- | -- |
+
+
+
+
+
+
+
+##### Docstring
+
+Deletes a user.
+
+
+
+
+
+### Docstring
+
+Central class for the user management.

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

@@ -0,0 +1,158 @@
+# Module `user_management.storage`
+
+## Class `InMemoryUserStorage`
+
+A simple in-memory storage for users.
+Intended for testing purposes only.
+
+
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self)
+```
+
+
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+#### Method `add`
+
+Adds a user.
+
+##### Method signature
+
+```python
+add(self, user: User) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `user` | `User` | normal | -- | -- |
+
+
+
+
+
+
+
+##### Docstring
+
+Adds a user.
+
+#### Method `get`
+
+Returns a user based on their ID.
+
+##### Method signature
+
+```python
+get(self, user_id: str) -> User
+```
+
+##### Returns
+
+Return type: `User`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `user_id` | `str` | normal | -- | -- |
+
+
+
+
+
+
+
+##### Docstring
+
+Returns a user based on their ID.
+
+#### Method `delete`
+
+Deletes a user.
+
+##### Method signature
+
+```python
+delete(self, user_id: str) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `user_id` | `str` | normal | -- | -- |
+
+
+
+
+
+
+
+##### Docstring
+
+Deletes a user.
+
+#### Method `list_all`
+
+Returns all users.
+
+##### Method signature
+
+```python
+list_all(self) -> list[User]
+```
+
+##### Returns
+
+Return type: `list[User]`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+
+
+
+
+
+
+
+##### Docstring
+
+Returns all users.
+
+
+
+
+
+### Docstring
+
+A simple in-memory storage for users.
+Intended for testing purposes only.

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

@@ -0,0 +1,61 @@
+# Module `user_management.utils`
+
+## Function `is_valid_email`
+
+Checks whether an email address is valid.
+
+### Function signature
+
+```python
+is_valid_email(email: str) -> bool
+```
+
+### Returns
+
+Return type: `bool`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `email` | `str` | normal | -- | -- |
+
+
+
+
+
+
+
+### Docstring
+
+Checks whether an email address is valid.
+
+## Function `normalize_name`
+
+Removes extra spaces and formats the name.
+
+### Function signature
+
+```python
+normalize_name(name: str) -> str
+```
+
+### Returns
+
+Return type: `str`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `str` | normal | -- | -- |
+
+
+
+
+
+
+
+### Docstring
+
+Removes extra spaces and formats the name.

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

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

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

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class User:
+    """
+    Represents a user.
+    """
+
+    id: str
+    name: str
+    email: str
+    age: int | None = None

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

@@ -0,0 +1,47 @@
+from .exceptions import InvalidEmailError, UserNotFoundError
+from .models import User
+from .storage import InMemoryUserStorage
+from .utils import is_valid_email, normalize_name
+
+
+class UserService:
+    """
+    Central class for the user management.
+    """
+
+    def __init__(self, storage: InMemoryUserStorage):
+        self.storage = storage
+
+    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}')
+
+        user = User(
+            id=user_id, name=normalize_name(name), email=email, age=age
+        )
+
+        self.storage.add(user)
+        return user
+
+    def get_user(self, user_id: str) -> User:
+        """
+        Returns a user.
+        """
+        try:
+            return self.storage.get(user_id)
+        except KeyError:
+            raise UserNotFoundError(user_id)
+
+    def delete_user(self, user_id: str) -> None:
+        """
+        Deletes a user.
+        """
+        try:
+            self.storage.delete(user_id)
+        except KeyError:
+            raise UserNotFoundError(user_id)

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

@@ -0,0 +1,27 @@
+from .models import User
+
+
+class InMemoryUserStorage:
+    """
+    A simple in-memory storage for users.
+    Intended for testing purposes only.
+    """
+
+    def __init__(self):
+        self._users: dict[str, User] = {}
+
+    def add(self, user: User) -> None:
+        """Adds a user."""
+        self._users[user.id] = user
+
+    def get(self, user_id: str) -> User:
+        """Returns a user based on their ID."""
+        return self._users[user_id]
+
+    def delete(self, user_id: str) -> None:
+        """Deletes a user."""
+        del self._users[user_id]
+
+    def list_all(self) -> list[User]:
+        """Returns all users."""
+        return list(self._users.values())

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

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

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

@@ -0,0 +1,32 @@
+# Copyright 2026 jCloud
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import pytest
+
+from src.jcloud_docsgen.core.python._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

@@ -0,0 +1,385 @@
+# 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 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.
+    :type source_code: str
+
+    :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:
+    """Adds two numbers."""
+    return a + b
+
+import typing
+
+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
+)
+import pytest
+
+@pytest.mark.parametrize('project_directory,docs_directory', [
+    (1, 1),
+    (1, None),
+    (42, None),
+    (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
+):
+    with pytest.raises(TypeError):
+        PythonDocumentationGenerator(project_directory, docs_directory)
+
+@pytest.mark.parametrize('python_documentation_generator,expected', [
+    (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_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,
+                                            [],
+                                        ),
+                                    ],
+                                ),
+                            ],
+                        ),
+                    ],
+                ),
+            ],
+        ),
+    ],
+)
+def test___collect_definitions(module, expected):
+    assert list(_collect_definitions(module)) == expected

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

@@ -0,0 +1,66 @@
+# Copyright 2026 jCloud
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import pytest
+
+from src.jcloud_docsgen.core.python._core import _fit_row_length
+
+
+@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

@@ -0,0 +1,199 @@
+# 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 docstring_parser
+import pytest
+
+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
+    :type docstring: str
+
+    :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', {}),
+        ([], '', {}),
+    ],
+)
+def test__function_params_types(arg_list, docstring, expected):
+    assert (
+        _function_params_info(arg_list, docstring_args_list(docstring))
+        == expected
+    )

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

@@ -0,0 +1,424 @@
+# Copyright 2026 jCloud
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import pytest
+
+from src.jcloud_docsgen.core.python._core import _markdown_table
+
+
+@pytest.mark.parametrize(
+    (
+        'header,body,allow_markdown_table,force_row_le'
+        'ngths,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_v'
+        'alues,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

@@ -0,0 +1,358 @@
+# Copyright 2026 jCloud
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import pytest
+
+from src.jcloud_docsgen.core.python._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