docs(changelog): add project directory structure entry

Added an entry that the implicit Python project directory
structure assumptions have been removed to the changelog.

.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,19 +1,18 @@
 # Changelog
 
-## [0.2.0] - 2026-09-28
+## [Unreleased]
 
 ### 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
+- Removed implicit project directory structure assumptions
 
 ### Deprecated
 

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

@@ -20,7 +20,6 @@ import argparse
 import pathlib
 import sys
 
-from ..exceptions import DirectoryNotEmptyError
 from .languages.python import VALID_SECTIONS as VALID_PYTHON_SECTIONS
 
 __all__ = [
@@ -82,15 +81,6 @@ def create_argument_parser() -> argparse.ArgumentParser:
         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()
 
@@ -160,7 +150,6 @@ def main(argv=None) -> int:
                 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')
@@ -168,8 +157,6 @@ def main(argv=None) -> int:
         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:

src/jcloud_docsgen/cli/languages/python.py

@@ -78,7 +78,6 @@ def _generate(
     ),
     allow_html: bool = False,
     allow_tables: bool = False,
-    force: bool = False,
 ) -> None:
     """
     Generates the documentation for a Python project.
@@ -95,9 +94,6 @@ def _generate(
     :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(
@@ -107,7 +103,7 @@ def _generate(
         allow_html=allow_html,
         allow_tables=allow_tables,
     )
-    docs_generator.generate_documentation(force)
+    docs_generator.generate_documentation()
 
 
 def generate(
@@ -118,7 +114,6 @@ def generate(
     exclude_sections: list[str] = [],
     allow_html: bool = False,
     allow_tables: bool = False,
-    force: bool = False,
 ) -> None:
     """
     Generates the documentation for a Python project.
@@ -138,9 +133,6 @@ def generate(
     :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)
@@ -151,5 +143,4 @@ def generate(
         include_sections=sections,
         allow_html=allow_html,
         allow_tables=allow_tables,
-        force=force,
     )

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,18 +16,13 @@ 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
 
-from ...exceptions import (
+from ...exceptions import InvalidNamespaceError, PythonArgumentStructureError
-    DirectoryNotEmptyError,
-    InvalidNamespaceError,
-    PythonArgumentStructureError,
-)
 from ...utils import get_relative_path_segments, non_empty_str
 from .arguments import PythonArgumentKind, PythonFunctionArgument
 from .definitions import (
@@ -249,8 +244,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 +272,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 +596,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'
 
@@ -1116,29 +1114,12 @@ class PythonDocumentationGenerator:
 
         return self._namespace(self.project_directory)
 
-    def generate_documentation(self, force: bool = False) -> None:
+    def generate_documentation(self) -> 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.
         """
 
-        if self.docs_directory.exists() and list(
-            self.docs_directory.iterdir()
-        ):
-            if force:
-                shutil.rmtree(self.docs_directory)
-            else:
-                raise DirectoryNotEmptyError(str(self.docs_directory))
         self.docs_directory.mkdir(parents=True, exist_ok=True)
 
         _generate_package_namespace_documentation(

src/jcloud_docsgen/core/python/namespaces.py

@@ -156,7 +156,7 @@ class PythonPackageNamespace(PythonNamespace):
         # For performance reasons, is not called self.sub_namespace_names
         # if the name attribute does not match, which can be quickly
         # verified
-        if not (isinstance(value, type(self)) and self.name == value.name):
+        if self.name != value.name:
             return False
 
         return value.sub_namespace_names() == self.sub_namespace_names()
@@ -223,4 +223,4 @@ class PythonModuleNamespace(PythonNamespace):
         super().__init__(name)
 
     def __eq__(self, value: PythonModuleNamespace) -> bool:
-        return isinstance(value, type(self)) and self.name == value.name
+        return self.name == value.name

src/jcloud_docsgen/exceptions.py

@@ -12,8 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import errno
-
 
 class NamespaceError(ValueError):
     """
@@ -28,11 +26,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 +53,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 +74,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,20 +95,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): ...
-
-
-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

@@ -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,7 +13,6 @@
 # limitations under the License.
 
 import pathlib
-import tempfile
 
 import pytest
 
@@ -175,30 +174,7 @@ def test_sections_success():
 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',
@@ -210,5 +186,3 @@ def test_docs_generation_error():
                 str(input_dir),
             ]
         )
-            == 1
-        )

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

@@ -13,16 +13,16 @@
 # limitations under the License.
 
 import pathlib
-import tempfile
 
 import pytest
 
+import tempfile
+
 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(
@@ -31,7 +31,7 @@ from src.jcloud_docsgen.exceptions import DirectoryNotEmptyError
         (
             PythonDocumentationGenerator(
                 pathlib.Path(
-                    'tests/unit/core/python/_core/test_project_dirs/pdir_1/src'
+                    'tests/unit/core/python/_core/test_project_dirs/pdir_1'
                 ),
                 pathlib.Path(
                     'tests/unit/core/python/_core/test_project_dirs/pdir_1/docs'
@@ -85,9 +85,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(
@@ -122,7 +120,7 @@ def test_generate_documentation(dir, expectdir):
             pathlib.Path(str(d)),
             allow_tables=True,
             allow_html=False,
-        ).generate_documentation(True)  # simplify the tests
+        ).generate_documentation()  # simplify the tests
 
 
 def test_creates_directory():
@@ -146,51 +144,3 @@ def test_creates_directory():
             )
             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/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

@@ -14,11 +14,7 @@
 
 import pytest
 
-from src.jcloud_docsgen.core.python.namespaces import (
+from src.jcloud_docsgen.core.python.namespaces import PythonModuleNamespace
-    PythonModuleNamespace,
-    PythonNamespace,
-    PythonPackageNamespace,
-)
 
 
 class StrSubclass(str): ...
@@ -46,10 +42,6 @@ def test_PythonModuleNamespace_name_attribute(namespace, expected_name):
         (PythonModuleNamespace('a'), PythonModuleNamespace('b'), False),
         (PythonModuleNamespace('0'), PythonModuleNamespace('-0'), False),
         (PythonModuleNamespace('1'), PythonModuleNamespace('a'), False),
-        (PythonModuleNamespace('a'), 'a', False),
-        (PythonModuleNamespace('a'), 'b', False),
-        (PythonModuleNamespace('a'), PythonPackageNamespace('a', []), False),
-        (PythonModuleNamespace('a'), PythonNamespace('a'), False),
     ],
 )
 def test_PythonModuleNamespace___eq__(namespace1, namespace2, expected):

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

@@ -16,7 +16,6 @@ import pytest
 
 from src.jcloud_docsgen.core.python.namespaces import (
     PythonModuleNamespace,
-    PythonNamespace,
     PythonPackageNamespace,
 )
 from src.jcloud_docsgen.exceptions import (
@@ -257,26 +256,6 @@ def test_PythonPackageNamespace_sub_namespace_names(namespace, expected):
             PythonPackageNamespace('b', []),
             False,
         ),
-        (
-            PythonPackageNamespace('a', []),
-            'a',
-            False,
-        ),
-        (
-            PythonPackageNamespace('a', []),
-            'b',
-            False,
-        ),
-        (
-            PythonPackageNamespace('a', []),
-            PythonModuleNamespace('a'),
-            False,
-        ),
-        (
-            PythonPackageNamespace('a', []),
-            PythonNamespace('a'),
-            False,
-        ),
     ],
 )
 def test_PythonPackageNamespace___eq__(namespace1, namespace2, expected):