diff --git a/pyproject.toml b/pyproject.toml index cbd28a4..e6bfcda 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -22,7 +22,7 @@ classifiers=[ dependencies = [ "click == 8.4.2", - "docstring-generator-ext>=2.0.4", + "docstring-generator-ext>=2.0.9", ] [dependency-groups] diff --git a/src/docstring_generator/new_gen_docs.py b/src/docstring_generator/new_gen_docs.py index 620f754..7aced5a 100644 --- a/src/docstring_generator/new_gen_docs.py +++ b/src/docstring_generator/new_gen_docs.py @@ -21,6 +21,14 @@ def find_pyproject_toml(start_paths: tuple[str, ...]) -> pathlib.Path | None: """ Walks up parent directories from the target files/directories to discover the project root's pyproject.toml. + + Parameters + ---------- + start_paths : tuple[str, Ellipsis] [Argument] + + Returns + ------- + Union[pathlib.Path, None] """ # Fallback to current working directory if no paths passed base_path = ( @@ -39,7 +47,15 @@ def find_pyproject_toml(start_paths: tuple[str, ...]) -> pathlib.Path | None: def load_toml_config(config_path: pathlib.Path | None) -> dict: - """Finds and parses configuration options from pyproject.toml.""" + """Finds and parses configuration options from pyproject.toml. + Parameters + ---------- + config_path : Union[pathlib.Path, None] [Argument] + + Returns + ------- + dict + """ if not config_path or not config_path.exists(): return {} @@ -95,6 +111,25 @@ def main( ignore_magic: bool, changed_only: bool, ) -> None: + """ + Parameters + ---------- + paths : tuple[str, Ellipsis] [Argument] + style : str [Argument] + check : bool [Argument] + strict : bool [Argument] + threshold : Union[int, None] [Argument] + exclude_file : list[str] [Argument] + exclude_dir : list[str] [Argument] + overwrite_style : bool [Argument] + dry_run : bool [Argument] + ignore_magic : bool [Argument] + changed_only : bool [Argument] + + Returns + ------- + None + """ docstring_style = STYLE_MAP[style] config = load_toml_config(find_pyproject_toml(paths)) @@ -167,7 +202,7 @@ def main( if check: checked_files = { file.absolute().as_posix(): docstring_generator_ext.check_docstring( - file.absolute().as_posix() + file.absolute().as_posix(), _ignore_magic ) for file in files_ } diff --git a/tests/test_library.py b/tests/test_library.py index 3ee3574..801a8e4 100644 --- a/tests/test_library.py +++ b/tests/test_library.py @@ -17,6 +17,11 @@ @pytest.mark.parametrize("style", ("numpy", "rest", "google")) def test_docstring_creation(style): + """ + Parameters + ---------- + style : [Argument] + """ with NamedTemporaryFile(suffix=".py", delete=False) as tmp_file: tmp_path = Path(tmp_file.name) tmp_file.write(BASE_EXAMPLE_FILE.read_bytes()) @@ -60,6 +65,11 @@ def test_check_coverage_no_coverage(): @pytest.mark.parametrize("test_file", EXPECTED_FILES.values()) def test_check_coverage_full_coverage(test_file): + """ + Parameters + ---------- + test_file : [Argument] + """ gendocs_new = Path(sys.executable).parent / "gendocs_new" result = subprocess.run( [str(gendocs_new), "--check", "--threshold", "95", str(test_file)], @@ -79,6 +89,11 @@ def test_check_coverage_full_coverage(test_file): @pytest.mark.parametrize("test_file", EXPECTED_FILES.values()) @pytest.mark.xfail def test_check_coverage_full_coverage_with_strict(test_file): + """ + Parameters + ---------- + test_file : [Argument] + """ gendocs_new = Path(sys.executable).parent / "gendocs_new" result = subprocess.run( [str(gendocs_new), "--check", "--threshold", "95", "--strict", str(test_file)], @@ -94,12 +109,29 @@ def test_check_coverage_full_coverage_with_strict(test_file): assert check_result["passing"] + +@pytest.mark.parametrize("test_file", EXPECTED_FILES.values()) +def test_check_coverage_full_coverage_with_ignore_magic(test_file): + """ + Parameters + ---------- + test_file : [Argument] + """ + from docstring_generator.new_gen_docs import main + main(["--check", "--ignore-magic", "--threshold", "95", str(test_file)], standalone_mode=False) + + with Path(Path.cwd(), "gendocs_check_output.json").open('r') as output_file: + import json + check_result = json.load(output_file) + + assert check_result["passing"] + + # --------------------------------------------------------------------------- # --dry-run tests # --------------------------------------------------------------------------- def test_dry_run_shows_diff_and_does_not_modify_file(): - """--dry-run must print a unified diff but leave the original file unchanged.""" gendocs_new = Path(sys.executable).parent / "gendocs_new" with NamedTemporaryFile(suffix=".py", delete=False) as tmp_file: @@ -131,7 +163,6 @@ def test_dry_run_shows_diff_and_does_not_modify_file(): def test_dry_run_reports_no_changes_for_fully_documented_file(): - """--dry-run should report 'no changes' for a file whose docstrings are already complete.""" gendocs_new = Path(sys.executable).parent / "gendocs_new" # Use a hand-crafted, minimal fixture that is genuinely idempotent (no raises → no edge cases) idempotent_file = Path(__file__).parent / "files" / "idempotent_example.py" @@ -153,7 +184,6 @@ def test_dry_run_reports_no_changes_for_fully_documented_file(): # --------------------------------------------------------------------------- def test_changed_only_aborts_when_git_not_found(): - """--changed-only must exit with a non-zero code when git is not on PATH.""" gendocs_new = Path(sys.executable).parent / "gendocs_new" with NamedTemporaryFile(suffix=".py", delete=False) as tmp_file: @@ -183,7 +213,6 @@ def test_changed_only_aborts_when_git_not_found(): def test_changed_only_processes_only_changed_files(): - """--changed-only must skip files that are not tracked as modified in git.""" gendocs_new = Path(sys.executable).parent / "gendocs_new" with TemporaryDirectory() as tmp_dir: @@ -243,7 +272,6 @@ def test_changed_only_processes_only_changed_files(): # --------------------------------------------------------------------------- def test_changed_only_combined_with_dry_run(): - """--changed-only --dry-run must show a diff only for changed files and not modify any file.""" gendocs_new = Path(sys.executable).parent / "gendocs_new" with TemporaryDirectory() as tmp_dir: