refactor(exceptions): define public module exports

Added an __all__ variable to the exceptions module.

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

@@ -16,7 +16,7 @@ name: Generate API reference
 
 on:
   push:
-    branch:
+    branches:
       - main
 
 permissions:

NOTICE

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

docs/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [Unreleased]
+
+### 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
+
 ## [0.2.0] - 2026-09-28
 
 ### Added

docs/reference/jcloud_docsgen/__init__.md

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

docs/reference/jcloud_docsgen/__main__.md

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

docs/reference/jcloud_docsgen/cli/__init__.md

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

docs/reference/jcloud_docsgen/cli/cli.md

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

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

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

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

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

docs/reference/jcloud_docsgen/core/__init__.md

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

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

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

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

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

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

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

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

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

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

@@ -73,7 +73,7 @@ A subclass of ``PythonNamespace`` for Python package namespaces.
 ##### Method signature
 
 ```python
-__init__(self, name: str, sub_namespaces: List[PythonNamespace]) -> None
+__init__(self, name: str, sub_namespaces: list[PythonNamespace]) -> None
 ```
 
 ##### Returns
@@ -86,7 +86,7 @@ Return type: `None`
 | --- | --- | --- | --- | --- |
 | `self` | -- | normal | -- | -- |
 | `name` | `str` | normal | -- | -- |
-| `sub_namespaces` | `List[PythonNamespace]` | normal | -- | -- |
+| `sub_namespaces` | `list[PythonNamespace]` | normal | -- | -- |
 
 #### Method `namespace`
 
@@ -96,7 +96,7 @@ Returns the namespace object with a specific identifier, such as
 ##### Method signature
 
 ```python
-namespace(self, sub_namespaces: List[str]) -> PythonNamespace
+namespace(self, sub_namespaces: list[str]) -> PythonNamespace
 ```
 
 ##### Returns
@@ -110,7 +110,7 @@ Return type: `PythonNamespace`
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
 | `self` | -- | normal | -- | -- |
-| `sub_namespaces` | `List[str]` | normal | -- | The identifier of the namespace. |
+| `sub_namespaces` | `list[str]` | normal | -- | The identifier of the namespace. |
 
 ##### Exceptions
 
@@ -347,12 +347,12 @@ Adds a namespace.
 ##### Method signature
 
 ```python
-sub_namespaces(self) -> List[PythonNamespace]
+sub_namespaces(self) -> list[PythonNamespace]
 ```
 
 ##### Returns
 
-Return type: `List[PythonNamespace]`
+Return type: `list[PythonNamespace]`
 
 ##### Parameters
 

docs/reference/jcloud_docsgen/exceptions.md

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

docs/reference/jcloud_docsgen/utils.md

@@ -37,7 +37,11 @@ Return type: `None`
 | `args` | -- | vararg | -- | -- |
 | `kwargs` | -- | kwargs | -- | -- |
 
+### Decorators
 
+```python
+deprecated('Use pathlib.Path instead.')
+```
 
 
 
@@ -84,7 +88,11 @@ Return type: `None`
 | `args` | -- | vararg | -- | -- |
 | `kwargs` | -- | kwargs | -- | -- |
 
+### Decorators
 
+```python
+deprecated('Use pathlib.Path instead.')
+```
 
 
 
@@ -230,7 +238,7 @@ attribute)
 ### Function signature
 
 ```python
-assert_that_is_instance(obj: object, class_or_tuple: Union[type, types.UnionType, tuple[type, ...]]) -> None
+assert_that_is_instance(obj: object, class_or_tuple: type | types.UnionType | tuple[type, ...]) -> None
 ```
 
 ### Returns
@@ -242,7 +250,7 @@ Return type: `None`
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
 | `obj` | `object` | normal | -- | -- |
-| `class_or_tuple` | `Union[type, types.UnionType, tuple[type, ...]]` | normal | -- | -- |
+| `class_or_tuple` | `type | types.UnionType | tuple[type, ...]` | normal | -- | -- |
 
 ## Function `non_empty_str`
 
@@ -256,20 +264,20 @@ Please note: values are stripped, i. e. if the value consists only
 ### Function signature
 
 ```python
-non_empty_str(value: Union[str, None]) -> Union[str, None]
+non_empty_str(value: str | None) -> str | None
 ```
 
 ### Returns
 
 The value or ``None``.
 
-Return type: `Union[str, None]`
+Return type: `str | None`
 
 ### Parameters
 
 | Parameter | Type | Kind | Default value | Description |
 | --- | --- | --- | --- | --- |
-| `value` | `Union[str, None]` | normal | -- | The value. |
+| `value` | `str | None` | normal | -- | The value. |
 
 
 
@@ -287,10 +295,10 @@ Please note: values are stripped, i. e. if the value consists only
              of spaces, it is also considered empty.
 
 :param value: The value.
-:type value: Union[str, None]
+:type value: str | None
 
 :return: The value or ``None``.
-:rtype: Union[str, None]
+:rtype: str | None
 
 ## Function `get_relative_path_segments`
 

licenses/docstring-parser.txt

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

licenses/iniconfig.txt

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

licenses/packaging.txt

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

licenses/pluggy.txt

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

licenses/pygments.txt

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

licenses/pytest-expectdir.txt

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

licenses/pytest.txt

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

src/jcloud_docsgen/core/python/_core.py

@@ -1096,10 +1096,20 @@ class PythonDocumentationGenerator:
         self.kwargs = kwargs
 
     def _namespace(self, directory: pathlib.Path) -> PythonPackageNamespace:
-        namespace = PythonPackageNamespace(directory.name, [])
+        namespace = PythonPackageNamespace(
+            # fallback for the case that the path it '/'. In this case, the
+            # name would be ''. The fallback value is irrelevant; the name is
+            # only specified because PythonPackageNamespace requires
+            # specifying it. The name will not be included in the generated
+            # output.
+            directory.resolve().name or 'project',
+            [],
+        )
 
         for entry in directory.iterdir():
-            if entry.is_dir():
+            if entry.is_dir() and (
+                entry.parent / (f'{entry.stem}.py')
+            ).resolve() not in [e.resolve() for e in entry.parent.iterdir()]:
                 namespace.add(self._namespace(entry))
             elif entry.suffix == '.py':
                 namespace.add(PythonModuleNamespace(entry.stem))

src/jcloud_docsgen/exceptions.py

@@ -14,6 +14,20 @@
 
 import errno
 
+__all__ = [
+    'NamespaceError',
+    'InvalidNamespaceError',
+    'NamespaceNotFoundError',
+    'NamespaceExistsError',
+    'PythonIdentifierError',
+    'InvalidPythonIdentifierError',
+    'PythonAnnotationError',
+    'InvalidPythonAnnotationError',
+    'PythonDefinitionError',
+    'PythonArgumentStructureError',
+    'DirectoryNotEmptyError',
+]
+
 
 class NamespaceError(ValueError):
     """

src/jcloud_docsgen/utils.py

@@ -27,6 +27,16 @@ 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):
     """

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

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