Feat(python-generator): protection against accidental overwriting of the output directory #40

2026-09-27T21:17:25+02:00

jakob.scheid commented

2026-09-27 21:17:25 +02:00

Accidental output directory overwriting protection

This pull request adds a protection against accidental overwriting of the output directory.

Why this?

Previously, using a non-empty output directory could lead to an inconsistent state of it: When you generated the documentation, changed some code, and generated it again, the documentation directory could include some old files which are not included in the new documentation version (e. g. because a module was renamed). That is why a protection is important: Either the output directory is completely emptied first and the documentation is generated, or an error that the directory is not empty occurs.

Summary

DirectoryNotEmptyError exception class (handled by CLI)
core functionality: added force argument to the Python documentation generator method and tests
CLI option (-f, --force) and tests
changelog entry

Related issues

Closes #33

# Accidental output directory overwriting protection This pull request adds a protection against accidental overwriting of the output directory. ## Why this? Previously, using a non-empty output directory could lead to an inconsistent state of it: When you generated the documentation, changed some code, and generated it again, the documentation directory could include some old files which are not included in the new documentation version (e. g. because a module was renamed). That is why a protection is important: Either the output directory is completely emptied first and the documentation is generated, or an error that the directory is not empty occurs. ## Summary - `DirectoryNotEmptyError` exception class (handled by CLI) - core functionality: added `force` argument to the Python documentation generator method and tests - CLI option (`-f`, `--force`) and tests - changelog entry ## Related issues Closes #33

jakob.scheid added this to the 0.2.0 milestone 2026-09-27 21:17:25 +02:00

jakob.scheid added the Kind/Documentation

Priority

Medium

3

Kind/Feature Compat/Breaking labels 2026-09-27 21:17:25 +02:00

jakob.scheid added this to the Project Board project 2026-09-27 21:17:25 +02:00

jakob.scheid added 6 commits 2026-09-27 21:17:26 +02:00

feat(exceptions): add DirectoryNotEmptyError 0261a7b3a6

Added an OSError subclass for indicating that the directory is not
empty. This exception is explicitly handled by the CLI now.

feat(python-generator): add force argument to generator 5791358b41

Added a force argument to
PythonDocumentationGenerator.generate_documentation to control whether
the content of the output directory should be overwritten or not, if it
is not empty. If the force argument is True, the output directory
content will first be deleted recursively. If it is False and the output
directory is not empty, a DirectoryNotEmptyError will be raised.

test(python-generator): add tests for force overwriting d8508e0fa3

Added tests to test new output directory deletion behavior:
  - output directory overwriting (not empty; force)
  - error (not empty; not force)
  - nothing (empty; force)
  - nothing (empty; not force)
One test was adapted to output directory emptiness check because the
.gitkeep file which is required for Git to track the directory makes it
non-empty.

feat(cli): add Python generator force argument f0c271f8fd

test(cli): add tests for Python force overwriting f2b9f47e09

Added a test to the CLI test file for the documentation generation
error.

docs(changelog): add accidental overwriting protection entry b043a4ea17

Added a changelog entry for the protection against accidental
overwriting of the output directory.

jakob.scheid moved this to Review in Project Board on 2026-09-27 21:17:31 +02:00

jakob.scheid merged commit 934624fce3 into main

2026-09-27 21:56:40 +02:00

jakob.scheid deleted branch feature/protect-against-accidental-overwriting

2026-09-27 21:56:40 +02:00

jakob.scheid moved this to Done in Project Board on 2026-09-27 21:56:45 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: jCloud/jcloud-docsgen#40