35 add ignore private and ignore uncommented flag support

.readthedocs.yaml

@@ -0,0 +1,24 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - build

README.md

@@ -172,6 +172,40 @@ gendocs_new mydir/ --style google --overwrite-style true
 
 Useful when migrating a codebase from one docstring convention to another.
 
+### `--ignore-private` — Skip private functions/methods
+
+Skip functions and methods whose name starts with a single underscore (e.g. `_helper`), leaving them untouched. Dunder methods (e.g. `__init__`, `__str__`) are **not** affected by this flag — use `--ignore-magic` for those:
+
+```shell
+gendocs_new mydir/ --ignore-private
+```
+
+Can also be enabled permanently via `pyproject.toml`:
+
+```toml
+[tool.docstring_generator]
+ignore_private = true
+```
+
+**Default:** `False`
+
+### `--ignore-uncommented` — Skip functions without an existing docstring
+
+Skip functions and methods that currently have **no docstring at all**, leaving them untouched instead of generating one. Good for simple helper functions where the name is already self-explanatory. Functions that already have *some* docstring are still processed normally (e.g. missing `Parameters`/`Returns` sections are added):
+
+```shell
+gendocs_new mydir/ --ignore-uncommented
+```
+
+Can also be enabled permanently via `pyproject.toml`:
+
+```toml
+[tool.docstring_generator]
+ignore_uncommented = true
+```
+
+**Default:** `False`
+
 ---
 
 ## Configuration via `pyproject.toml`
@@ -185,12 +219,58 @@ threshold = 90
 exclude_files = ["conftest.py", "settings.py"]
 exclude_dirs = ["tests", "migrations"]
 ignore_magic = true
+ignore_private = true
+ignore_uncommented = true
 ```
 
 CLI flags always override `pyproject.toml` values. The tool automatically walks up from the target path to find the nearest `pyproject.toml`.
 
 ---
 
+## Skip Directives — `# docstring: skip` / `# docstring: off` / `# docstring: on`
+
+When a CLI flag is too coarse, tell the generator to leave specific parts of a file untouched using `# docstring: skip` comments. Three scopes are supported:
+
+### 1. File-level skip
+
+Place the directive within the first 10 lines of the file to skip the entire file:
+
+```python
+# docstring: skip
+
+def some_function():
+    return None
+```
+
+### 2. Single-target skip
+
+Place the directive as the first statement inside a function or method body to skip just that target:
+
+```python
+def helper_three(a: int) -> int:
+    # docstring: skip
+    return a
+```
+
+### 3. Block/Range skip
+
+Wrap a group of functions or classes between `# docstring: off` and `# docstring: on` to skip everything in between:
+
+```python
+# docstring: off
+def helper_one():
+    ...
+
+
+def helper_two():
+    ...
+# docstring: on
+```
+
+> ⚠️ **Known limitation:** currently only the function immediately following `# docstring: off` is reliably skipped — functions further down the block may still receive a generated docstring. Until this is fixed upstream, prefer the single-target directive on each function if you need every function in a range excluded. See the full [Skip Directives guide](https://felixthec.github.io/docstring_generator/skip-directives/) for details.
+
+---
+
 ## Preserve Custom Descriptions with `$<num>` Placeholders
 
 Write your domain-specific notes once — `docstring_generator` will place them in the right parameter slot automatically.

docs/configuration.md

@@ -9,6 +9,8 @@ threshold = 90
 exclude_files = ["conftest.py", "settings.py"]
 exclude_dirs = ["tests", "migrations"]
 ignore_magic = true
+ignore_private = true
+ignore_uncommented = true
 ```
 
 CLI flags always override `pyproject.toml` values. The tool automatically walks up from the target path to find the nearest `pyproject.toml`.
@@ -22,3 +24,7 @@ CLI flags always override `pyproject.toml` values. The tool automatically walks
 | `exclude_files` | list of str | `--exclude-file` | File names to skip |
 | `exclude_dirs` | list of str | `--exclude-dir` | Directory names to skip |
 | `ignore_magic` | bool | `--ignore-magic` | Skip dunder/magic methods |
+| `ignore_private` | bool | `--ignore-private` | Skip functions/methods whose name starts with a single underscore (dunder methods are unaffected) |
+| `ignore_uncommented` | bool | `--ignore-uncommented` | Skip functions/methods that currently have no docstring at all |
+
+> Looking for the `# docstring: skip` / `# docstring: off` / `# docstring: on` comment directives? Those aren't configured via `pyproject.toml` — see the [Skip Directives](skip-directives.md) page.

docs/options.md

@@ -132,3 +132,49 @@ gendocs_new mydir/ --style google --overwrite-style true
 ```
 
 Useful when migrating a codebase from one docstring convention to another.
+
+---
+
+## `--ignore-private` — Skip private functions/methods
+
+Skip functions and methods whose name starts with a single underscore (e.g. `_helper`), leaving them untouched. Dunder methods (e.g. `__init__`, `__str__`) are **not** affected by this flag — use `--ignore-magic` for those:
+
+```shell
+gendocs_new mydir/ --ignore-private
+```
+
+Can also be enabled permanently via `pyproject.toml`:
+
+```toml
+[tool.docstring_generator]
+ignore_private = true
+```
+
+**Default:** `False`
+
+---
+
+## `--ignore-uncommented` — Skip functions without an existing docstring
+
+Skip functions and methods that currently have **no docstring at all**, leaving them untouched instead of generating one. This is useful for simple helper functions where the name is already self-explanatory and you don't want the tool to add boilerplate:
+
+```shell
+gendocs_new mydir/ --ignore-uncommented
+```
+
+Functions that already have *some* docstring are still processed normally (e.g. missing `Parameters`/`Returns` sections are added). Only fully undocumented functions are skipped.
+
+Can also be enabled permanently via `pyproject.toml`:
+
+```toml
+[tool.docstring_generator]
+ignore_uncommented = true
+```
+
+**Default:** `False`
+
+---
+
+## Skip Directives — `# docstring: skip` / `# docstring: off` / `# docstring: on`
+
+Sometimes a flag is too coarse — you want to skip *specific* files, functions, or classes without changing how the rest of the codebase is processed. For that, `docstring_generator` supports inline comment directives. See the [Skip Directives](skip-directives.md) page for the full guide with examples for each of the three supported scopes (file-level, single-target, and block/range).

docs/requirements.txt

@@ -0,0 +1,33 @@
+attrs>=21.2.0
+certifi>=2024.7.4
+chardet>=4.0.0
+click>=8.0.0
+codecov>=2.1.13
+coverage>=5.5
+future>=0.18.2
+idna>=2.10
+Jinja2>=3.1.5
+joblib>=1.2.0
+livereload>=2.6.3
+lunr>=0.5.8
+Markdown>=3.3.4
+MarkupSafe>=2.0.1
+mkdocs>=1.1.2
+more-itertools>=8.7.0
+nltk>=3.6.2
+packaging>=20.9
+pluggy>=0.13.1
+py>=1.10.0
+pyparsing>=2.4.7
+pytest>=5.4.1
+pytest-cov>=2.12.0
+PyYAML>=6.0.2
+regex>=2021.4.4
+requests>=2.25.1
+six>=1.16.0
+toml>=0.10.2
+tornado>=6.1
+tqdm>=4.60.0
+ujson>=5.4.0
+urllib3>=1.26.5
+wcwidth>=0.2.5

docs/skip-directives.md

@@ -0,0 +1,72 @@
+# Skip Directives
+
+CLI flags like `--ignore-private` or `--exclude-file` apply uniformly to a whole run. Sometimes you need something more surgical — skip *this one file*, *this one function*, or *this group of helpers* — without changing how the rest of the codebase is processed.
+
+For that, `docstring_generator` understands special `# docstring: ...` comments directly in your source code. Three scopes are supported.
+
+---
+
+## 1. File-level skip
+
+Place `# docstring: skip` within the **first 10 lines** of the file to skip the entire file — nothing in it will be touched:
+
+```python
+# docstring: skip
+
+def some_function():
+    return None
+```
+
+Running `gendocs_new` on this file leaves it byte-for-byte unchanged. This is the right choice for generated files, vendored code, or files you never want auto-documented.
+
+> The directive must appear within the first 10 lines. If it appears later, it is treated as a comment and has no effect at the file level.
+
+---
+
+## 2. Single-target skip
+
+Place the directive as the **first statement inside a function or method body** to skip just that one target:
+
+```python
+def helper_three(a: int) -> int:
+    # docstring: skip
+    return a
+
+
+def normal_func(a: int) -> int:
+    return a
+```
+
+Here, only `helper_three` is left untouched — `normal_func` still gets a docstring generated normally. This is the most precise way to opt a single function or method out of documentation, e.g. for trivial one-liners or intentionally undocumented internals.
+
+---
+
+## 3. Block/Range skip
+
+Wrap a group of functions or classes between `# docstring: off` and `# docstring: on` to skip everything in between:
+
+```python
+# docstring: off
+def helper_one():
+    ...
+
+
+def helper_two():
+    ...
+# docstring: on
+```
+
+!!! warning "Known limitation"
+    In the current version of the underlying `docstring-generator-ext` engine, only the function **immediately following** `# docstring: off` is reliably skipped. Additional functions further down in the block (before the matching `# docstring: on`) may still receive generated docstrings. This is tracked as a known issue — until it's fixed upstream, prefer the [single-target skip](#2-single-target-skip) directive on each function you want to exclude if you need a guarantee that *every* function in a range is skipped.
+
+---
+
+## Choosing the right scope
+
+| Scope | Directive | Effect |
+|-------|-----------|--------|
+| File-level | `# docstring: skip` (first 10 lines) | Skips the entire file |
+| Single-target | `# docstring: skip` (first line inside a function/method body) | Skips just that function/method |
+| Block/range | `# docstring: off` ... `# docstring: on` | Intended to skip everything in between (see limitation above) |
+
+These directives compose with all CLI flags — e.g. you can run `gendocs_new --ignore-magic mydir/` while still using `# docstring: skip` to opt individual functions out of documentation.

mkdocs.yml

@@ -46,6 +46,7 @@ nav:
   - Installation: installation.md
   - CLI Options: options.md
   - Configuration: configuration.md
+  - Skip Directives: skip-directives.md
   - Features: features.md
   - Pre-commit: pre-commit.md
   - IDE Integration: ide-integration.md

pyproject.toml

@@ -22,7 +22,7 @@ classifiers=[
 
 dependencies = [
     "click == 8.4.2",
-    "docstring-generator-ext==2.0.14",
+    "docstring-generator-ext==2.1.0",
 ]
 
 [dependency-groups]

src/docstring_generator/__init__.py

@@ -1,6 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-@created: 01.08.21
-@author: felix
-"""