test(python-generator): add test cases for package namespace comparision

Added test cases with different types for Python package namespace
comparision test.

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

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

docs/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## [0.2.0] - 2026-09-28
+## [Unreleased]
 
 ### Added
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "jcloud-docsgen"
-version = "0.2.0"
+version = "0.1.0"
 description = "A tool that generates Markdown documentation for software project source code"
 dependencies = ["docstring-parser"]
 requires-python = ">=3.10"

src/jcloud_docsgen/__init__.py

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

src/jcloud_docsgen/core/python/__init__.py

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

src/jcloud_docsgen/core/python/_core.py

@@ -16,13 +16,14 @@ from __future__ import annotations
 
 import ast
 import pathlib
-import shutil
 from collections.abc import Iterator
 from dataclasses import dataclass
 from typing import TypeAlias
 
 import docstring_parser
 
+import shutil
+
 from ...exceptions import (
     DirectoryNotEmptyError,
     InvalidNamespaceError,
@@ -249,8 +250,9 @@ def _markdown_table(
             if len(row) != header_len:
                 if force_row_lengths:
                     raise ValueError(
-                        f'expected {header_len} value'
+                        f'expected {header_len} value{
-                        f'{"s" if header_len > 1 else ""}, got {len(row)}'
+                            "s" if header_len > 1 else ""
+                        }, got {len(row)}',
                     )
                 else:
                     row = _fit_row_length(header_len, row)
@@ -276,8 +278,9 @@ def _markdown_table(
             if len(row) != header_len:
                 if force_row_lengths:
                     raise ValueError(
-                        f'expected {header_len} value'
+                        f'expected {header_len} value{
-                        f'{"s" if header_len > 1 else ""}, got {len(row)}'
+                            "s" if header_len > 1 else ""
+                        }, got {len(row)}',
                     )
                 else:
                     row = _fit_row_length(header_len, row)
@@ -599,10 +602,11 @@ class PythonDefinitionDocumentationGenerator:
 
         if _is_docstring(self.definition.doc) or not self.skip_empty_sections:
             if self.allow_html:
-                md += (
+                md += f'<details><summary><h{
-                    f'<details><summary><h{str(self.level + 1)} style="displa'
+                    str(self.level + 1)
-                    f'y:inline">Docstring</h{str(self.level + 1)}></summary>'
+                } style="display:inline">Docstring</h{
-                )
+                    str(self.level + 1)
+                }></summary>'
             else:
                 md += self.level * '#' + '# Docstring\n\n'
 

src/jcloud_docsgen/exceptions.py

@@ -28,11 +28,9 @@ class NamespaceError(ValueError):
         if not self.args:
             return ''
         else:
-            return (
+            return f'{self.args[0]}{
-                self.args[0]
+                ": " if self.namespace_identifier and self.args[0] else ""
-                + (': ' if self.namespace_identifier and self.args[0] else '')
+            }{self.namespace_identifier if self.args[0] else ""}'
-                + (self.namespace_identifier if self.args[0] else '')
-            )
 
 
 class InvalidNamespaceError(NamespaceError): ...
@@ -57,11 +55,9 @@ class PythonIdentifierError(ValueError):
         if not self.args:
             return ''
         else:
-            return (
+            return f'{self.args[0]}{
-                self.args[0]
+                ": " if self.identifier and self.args[0] else ""
-                + (': ' if self.identifier and self.args[0] else '')
+            }{self.identifier if self.args[0] else ""}'
-                + (self.identifier if self.args[0] else '')
-            )
 
 
 class InvalidPythonIdentifierError(PythonIdentifierError): ...
@@ -80,11 +76,9 @@ class PythonAnnotationError(ValueError):
         if not self.args:
             return ''
         else:
-            return (
+            return f'{self.args[0]}{
-                self.args[0]
+                ": " if self.annotation and self.args[0] else ""
-                + (': ' if self.annotation and self.args[0] else '')
+            }{self.annotation if self.args[0] else ""}'
-                + (self.annotation if self.args[0] else '')
-            )
 
 
 class InvalidPythonAnnotationError(PythonAnnotationError): ...
@@ -103,11 +97,9 @@ class PythonDefinitionError(ValueError):
         if not self.args:
             return ''
         else:
-            return (
+            return f'{self.args[0]}{
-                self.args[0]
+                ": " if self.definition and self.args[0] else ""
-                + (': ' if self.definition and self.args[0] else '')
+            }{self.definition if self.args[0] else ""}'
-                + (self.definition if self.args[0] else '')
-            )
 
 
 class PythonArgumentStructureError(PythonDefinitionError): ...

src/jcloud_docsgen/utils.py

@@ -20,6 +20,7 @@ import errno
 import os
 import pathlib
 import types
+from typing import Union
 
 try:
     from warnings import deprecated
@@ -153,10 +154,10 @@ def assert_that_is_instance(
     obj: object,
     class_or_tuple: type | types.UnionType | tuple[type, ...],
 ) -> None:
-    if not isinstance(class_or_tuple, (type, types.UnionType, tuple)):
+    if not isinstance(class_or_tuple, Union[type, types.UnionType, tuple]):
         raise TypeError(
-            f"class_or_tuple: expected 'type | types.UnionType, tupl"
+            f"class_or_tuple: expected 'Union[type, types.UnionType, "
-            f"e[type, ...]', 'got {type(class_or_tuple).__name__}'",
+            f"tuple[type, ...]]', 'got {type(class_or_tuple).__name__}'",
         )
     if not isinstance(obj, class_or_tuple):
         if isinstance(class_or_tuple, (tuple, types.UnionType)):
@@ -174,8 +175,9 @@ def assert_that_is_instance(
         else:
             exception_message_expected = "'" + class_or_tuple.__name__ + "'"
         raise TypeError(
-            f'expected {exception_message_expected}'
+            f"expected {exception_message_expected}, got '{
-            f", got '{type(obj).__name__}'"
+                type(obj).__name__
+            }'",
         )
 
 

tests/unit/cli/test_python.py

@@ -13,10 +13,11 @@
 # limitations under the License.
 
 import pathlib
-import tempfile
 
 import pytest
 
+import tempfile
+
 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

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

@@ -13,16 +13,17 @@
 # limitations under the License.
 
 import pathlib
-import tempfile
 
 import pytest
 
+import tempfile
+
+from src.jcloud_docsgen.exceptions import DirectoryNotEmptyError
 from src.jcloud_docsgen.core.python import PythonDocumentationGenerator
 from src.jcloud_docsgen.core.python.namespaces import (
     PythonModuleNamespace,
     PythonPackageNamespace,
 )
-from src.jcloud_docsgen.exceptions import DirectoryNotEmptyError
 
 
 @pytest.mark.parametrize(
@@ -85,9 +86,7 @@ def test_PythonDocumentationGenerator_collect_modules(
     python_documentation_generator: PythonDocumentationGenerator,
     expected,
 ):
-    assert (
+    assert python_documentation_generator.namespace().sub_namespaces == expected
-        python_documentation_generator.namespace().sub_namespaces
-    ) == expected
 
 
 @pytest.mark.parametrize(

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

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

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

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

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

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

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

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

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

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

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

@@ -15,8 +15,8 @@
 import pytest
 
 from src.jcloud_docsgen.core.python.namespaces import (
-    PythonModuleNamespace,
     PythonNamespace,
+    PythonModuleNamespace,
     PythonPackageNamespace,
 )
 

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

@@ -15,8 +15,8 @@
 import pytest
 
 from src.jcloud_docsgen.core.python.namespaces import (
-    PythonModuleNamespace,
     PythonNamespace,
+    PythonModuleNamespace,
     PythonPackageNamespace,
 )
 from src.jcloud_docsgen.exceptions import (