From 0fbfe8465771dfc4235a52f85ad84855fa0fafd4 Mon Sep 17 00:00:00 2001 From: Jakob Scheid Date: Tue, 22 Sep 2026 17:52:00 +0200 Subject: [PATCH 1/3] feat(python-generator)!: do not require specific structure Removed all implicit assumptions of a project structure: - no 'src/' directory is required - top-level modules are no longer ignored --- src/jcloud_docsgen/cli/cli.py | 4 +--- src/jcloud_docsgen/core/python/_core.py | 16 ++++++---------- 2 files changed, 7 insertions(+), 13 deletions(-) diff --git a/src/jcloud_docsgen/cli/cli.py b/src/jcloud_docsgen/cli/cli.py index ae22588..1fae4e0 100644 --- a/src/jcloud_docsgen/cli/cli.py +++ b/src/jcloud_docsgen/cli/cli.py @@ -78,6 +78,7 @@ def create_argument_parser() -> argparse.ArgumentParser: '-o', '--output-dir', type=pathlib.Path, + default='docs/reference', help='the output directory the documentation will be written to', ) @@ -138,9 +139,6 @@ def main(argv=None) -> int: argument_parser = create_argument_parser() args = argument_parser.parse_args(argv) - if args.output_dir is None: - args.output_dir = args.project_directory / 'docs/reference' - try: if args.language == _LANG_PYTHON: from .languages.python import generate diff --git a/src/jcloud_docsgen/core/python/_core.py b/src/jcloud_docsgen/core/python/_core.py index f28fc10..73b6b26 100644 --- a/src/jcloud_docsgen/core/python/_core.py +++ b/src/jcloud_docsgen/core/python/_core.py @@ -1104,19 +1104,15 @@ class PythonDocumentationGenerator: return namespace - def namespace(self) -> list[PythonPackageNamespace]: + def namespace(self) -> PythonPackageNamespace: """ Returns the project as a namespace. :return: The project as a namespace. - :rtype: list[PythonPackageNamespace] + :rtype: PythonPackageNamespace: """ - src_dir = self.project_directory / 'src' - - return [ - self._namespace(dir) for dir in src_dir.iterdir() if dir.is_dir() - ] + return self._namespace(self.project_directory) def generate_documentation(self) -> None: """ @@ -1127,10 +1123,10 @@ class PythonDocumentationGenerator: self.docs_directory.mkdir(parents=True, exist_ok=True) _generate_package_namespace_documentation( - PythonPackageNamespace('src', self.namespace()), + self.namespace(), self.docs_directory, - self.project_directory / 'src', - self.project_directory / 'src', + self.project_directory, + self.project_directory, self.include_sections, self.kwargs, ) From c40e965d8d53d3bba04036126c27847619451c3e Mon Sep 17 00:00:00 2001 From: Jakob Scheid Date: Tue, 22 Sep 2026 18:25:55 +0200 Subject: [PATCH 2/3] test(python-generator): update tests to do not assume src/ directories Updated tests to do not implicitly assume a 'src/' directory structure and removed all 'src/' subdirectory structures in test project directories (if possible). --- .../cli/python_project/project/{src => }/pkg/module.py | 0 .../python/_core/test_PythonDocumentationGenerator.py | 10 +++++----- .../case01/project/{src => }/.gitkeep | 0 .../case02/project/{src => }/pkg/module.py | 0 .../project/{src => }/user_management/exceptions.py | 0 .../case03/project/{src => }/user_management/models.py | 0 .../project/{src => }/user_management/service.py | 0 .../project/{src => }/user_management/storage.py | 0 .../case03/project/{src => }/user_management/utils.py | 0 9 files changed, 5 insertions(+), 5 deletions(-) rename tests/unit/cli/python_project/project/{src => }/pkg/module.py (100%) rename tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case01/project/{src => }/.gitkeep (100%) rename tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/{src => }/pkg/module.py (100%) rename tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/{src => }/user_management/exceptions.py (100%) rename tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/{src => }/user_management/models.py (100%) rename tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/{src => }/user_management/service.py (100%) rename tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/{src => }/user_management/storage.py (100%) rename tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/{src => }/user_management/utils.py (100%) diff --git a/tests/unit/cli/python_project/project/src/pkg/module.py b/tests/unit/cli/python_project/project/pkg/module.py similarity index 100% rename from tests/unit/cli/python_project/project/src/pkg/module.py rename to tests/unit/cli/python_project/project/pkg/module.py diff --git a/tests/unit/core/python/_core/test_PythonDocumentationGenerator.py b/tests/unit/core/python/_core/test_PythonDocumentationGenerator.py index 89612b9..36f095f 100644 --- a/tests/unit/core/python/_core/test_PythonDocumentationGenerator.py +++ b/tests/unit/core/python/_core/test_PythonDocumentationGenerator.py @@ -31,7 +31,7 @@ from src.jcloud_docsgen.core.python.namespaces import ( ( PythonDocumentationGenerator( pathlib.Path( - 'tests/unit/core/python/_core/test_project_dirs/pdir_1' + 'tests/unit/core/python/_core/test_project_dirs/pdir_1/src' ), pathlib.Path( 'tests/unit/core/python/_core/test_project_dirs/pdir_1/docs' @@ -42,7 +42,7 @@ from src.jcloud_docsgen.core.python.namespaces import ( ( PythonDocumentationGenerator( pathlib.Path( - 'tests/unit/core/python/_core/test_project_dirs/pdir_2' + 'tests/unit/core/python/_core/test_project_dirs/pdir_2/src' ), pathlib.Path( 'tests/unit/core/python/_core/test_project_dirs/pdir_2/docs' @@ -58,7 +58,7 @@ from src.jcloud_docsgen.core.python.namespaces import ( ( PythonDocumentationGenerator( pathlib.Path( - 'tests/unit/core/python/_core/test_project_dirs/pdir_3' + 'tests/unit/core/python/_core/test_project_dirs/pdir_3/src' ), pathlib.Path( 'tests/unit/core/python/_core/test_project_dirs/pdir_3/docs' @@ -85,7 +85,7 @@ def test_PythonDocumentationGenerator_collect_modules( python_documentation_generator: PythonDocumentationGenerator, expected, ): - assert python_documentation_generator.namespace() == expected + assert python_documentation_generator.namespace().sub_namespaces == expected @pytest.mark.parametrize( @@ -130,7 +130,7 @@ def test_creates_directory(): project_dir = pathlib.Path(project_dir) # The directory of the package - package_dir = project_dir / 'src' / 'pkg' + package_dir = project_dir / 'pkg' assert not package_dir.exists() package_dir.mkdir(parents=True, exist_ok=True) diff --git a/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case01/project/src/.gitkeep b/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case01/project/.gitkeep similarity index 100% rename from tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case01/project/src/.gitkeep rename to tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case01/project/.gitkeep diff --git a/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/src/pkg/module.py b/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/module.py similarity index 100% rename from tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/src/pkg/module.py rename to tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case02/project/pkg/module.py diff --git a/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/src/user_management/exceptions.py b/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/user_management/exceptions.py similarity index 100% rename from tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/src/user_management/exceptions.py rename to tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/user_management/exceptions.py diff --git a/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/src/user_management/models.py b/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/user_management/models.py similarity index 100% rename from tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/src/user_management/models.py rename to tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/user_management/models.py diff --git a/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/src/user_management/service.py b/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/user_management/service.py similarity index 100% rename from tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/src/user_management/service.py rename to tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/user_management/service.py diff --git a/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/src/user_management/storage.py b/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/user_management/storage.py similarity index 100% rename from tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/src/user_management/storage.py rename to tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/user_management/storage.py diff --git a/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/src/user_management/utils.py b/tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/user_management/utils.py similarity index 100% rename from tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/src/user_management/utils.py rename to tests/unit/core/python/_core/test_PythonDocumentationGenerator/test_generate_documentation/case03/project/user_management/utils.py From 53ab0e3829e70290da90688bfcd5ffef5453cb3b Mon Sep 17 00:00:00 2001 From: Jakob Scheid Date: Tue, 22 Sep 2026 18:34:38 +0200 Subject: [PATCH 3/3] docs(changelog): add project directory structure entry Added an entry that the implicit Python project directory structure assumptions have been removed to the changelog. --- docs/CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 461a886..731d028 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -12,6 +12,7 @@ - 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