From 78b4566c908e9d4f3b8d7a1a8cf08df0e856005a Mon Sep 17 00:00:00 2001 From: Stefanie Molin <24376333+stefmolin@users.noreply.github.com> Date: Sat, 25 Oct 2025 12:17:32 -0300 Subject: [PATCH 1/7] Update README --- README.md | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index c62c4ed..61ab4c9 100644 --- a/README.md +++ b/README.md @@ -54,12 +54,12 @@ def say_hello(name: str = 'World') -> None: You can use Docstringify in three modes: -1. Flag missing docstrings: +1. `check`: Flag missing docstrings: ``` test is missing a docstring test.say_hello is missing a docstring ``` -2. Suggest docstring templates based on type annotations: +2. `suggest`: Suggest docstring templates based on type annotations: ``` test is missing a docstring Hint: @@ -76,7 +76,7 @@ You can use Docstringify in three modes: __description__ """ ``` -3. Add docstring templates to source code files: +3. `edit`: Add docstring templates to source code files: ```python """__description__""" @@ -100,49 +100,49 @@ Add the following to your `.pre-commit-config.yaml` file to block commits with m ```yaml - repo: https://github.com/stefmolin/docstringify - rev: 1.1.1 + rev: hooks: - - id: docstringify + - id: docstringify-check ``` By default, all docstrings are required. If you want to be more lenient, you can set the threshold, which is the percentage of docstrings that must be present: ```yaml - repo: https://github.com/stefmolin/docstringify - rev: 1.1.1 + rev: hooks: - - id: docstringify + - id: docstringify-check args: [--threshold=0.75] ``` -If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `"""__description__"""`): +If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), use the `suggest` mode, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `"""__description__"""`): ```yaml - repo: https://github.com/stefmolin/docstringify - rev: 1.1.1 + rev: hooks: - - id: docstringify - args: [--suggest-changes=numpydoc] + - id: docstringify-suggest + args: [--style=numpydoc] ``` -Use `--make-changes` to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html): +Use the `edit` mode to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html): ```yaml - repo: https://github.com/stefmolin/docstringify - rev: 1.1.1 + rev: hooks: - - id: docstringify - args: [--make-changes=google] + - id: docstringify-edit + args: [--style=google] ``` -If you want the changes to be made in place, change `--make-changes` to `--make-changes-inplace` – make sure you only operate on files that are in version control with this setting. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions: +If you want the changes to be made in place, add `--overwrite` – make sure you only operate on files that are in version control with this setting. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions: ```yaml - repo: https://github.com/stefmolin/docstringify - rev: 1.1.1 + rev: hooks: - - id: docstringify - args: [--make-changes-inplace=numpydoc] + - id: docstringify-edit + args: [--overwrite, --style=numpydoc] ``` Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options. @@ -155,10 +155,10 @@ First, install the `docstringify` package from PyPI: $ python -m pip install docstringify ``` -Then, use the `docstringify` entry point on the file(s) of your choice: +Then, use the `docstringify` entry point on the file(s) of your choice. For example, to run in `check` mode: ```shell -$ docstringify /path/to/file [/path/to/another/file] +$ docstringify check /path/to/file [/path/to/another/file] ``` Run `docstringify --help` for more information. From 97d9720f14c419ce6b8277ac2a82fccc6aed736e Mon Sep 17 00:00:00 2001 From: Stefanie Molin <24376333+stefmolin@users.noreply.github.com> Date: Sat, 25 Oct 2025 12:17:42 -0300 Subject: [PATCH 2/7] Bump version --- pyproject.toml | 2 +- uv.lock | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 12905e6..6aebd10 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ requires = [ "hatchling" ] [project] name = "docstringify" -version = "1.1.1" +version = "2.0.0" description = "Flag missing docstrings and, optionally, generate them from signatures and type annotations." readme = "README.md" keywords = [ diff --git a/uv.lock b/uv.lock index 8e28a03..aadfc09 100644 --- a/uv.lock +++ b/uv.lock @@ -90,7 +90,7 @@ wheels = [ [[package]] name = "docstringify" -version = "1.1.1" +version = "2.0.0" source = { editable = "." } [package.dev-dependencies] From ba039f1cd4769da7b4d66fd004ef33a294e88cb0 Mon Sep 17 00:00:00 2001 From: Stefanie Molin <24376333+stefmolin@users.noreply.github.com> Date: Sat, 25 Oct 2025 12:19:16 -0300 Subject: [PATCH 3/7] Update formatting --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 61ab4c9..9197e3c 100644 --- a/README.md +++ b/README.md @@ -55,11 +55,13 @@ def say_hello(name: str = 'World') -> None: You can use Docstringify in three modes: 1. `check`: Flag missing docstrings: + ``` test is missing a docstring test.say_hello is missing a docstring ``` 2. `suggest`: Suggest docstring templates based on type annotations: + ``` test is missing a docstring Hint: @@ -77,6 +79,7 @@ You can use Docstringify in three modes: """ ``` 3. `edit`: Add docstring templates to source code files: + ```python """__description__""" From 5e5c1311cbceb5104ced0e1cff435e6c505f7e00 Mon Sep 17 00:00:00 2001 From: Stefanie Molin <24376333+stefmolin@users.noreply.github.com> Date: Sat, 25 Oct 2025 12:21:54 -0300 Subject: [PATCH 4/7] Update README with version compatibility note --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 9197e3c..8452f28 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,9 @@ You can use Docstringify in three modes: ### Pre-commit hook +> [!NOTE] +> The examples in this section apply to versions 2.0.0 and greater. If you are using an older version, consult the README at that tag. + Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`: ```yaml From 7c6be6a0f3d7ba00dbf5e858baae7d10ae99c9d5 Mon Sep 17 00:00:00 2001 From: Stefanie Molin <24376333+stefmolin@users.noreply.github.com> Date: Sat, 25 Oct 2025 12:24:53 -0300 Subject: [PATCH 5/7] Add subsections for hook modes --- README.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8452f28..ff8013c 100644 --- a/README.md +++ b/README.md @@ -102,6 +102,8 @@ You can use Docstringify in three modes: > [!NOTE] > The examples in this section apply to versions 2.0.0 and greater. If you are using an older version, consult the README at that tag. +#### Check mode + Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`: ```yaml @@ -121,6 +123,8 @@ By default, all docstrings are required. If you want to be more lenient, you can args: [--threshold=0.75] ``` +#### Suggest mode + If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), use the `suggest` mode, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `"""__description__"""`): ```yaml @@ -131,6 +135,8 @@ If you would like to see suggested docstring templates (inferred from type annot args: [--style=numpydoc] ``` +#### Edit mode + Use the `edit` mode to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html): ```yaml @@ -141,7 +147,7 @@ Use the `edit` mode to create a copy of each file with docstring templates. Here args: [--style=google] ``` -If you want the changes to be made in place, add `--overwrite` – make sure you only operate on files that are in version control with this setting. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions: +If you want the changes to be made in place, add `--overwrite`. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions: ```yaml - repo: https://github.com/stefmolin/docstringify @@ -151,6 +157,9 @@ If you want the changes to be made in place, add `--overwrite` – make sure args: [--overwrite, --style=numpydoc] ``` +> [!WARNING] +> Make sure you only operate on files that are in version control with this setting. + Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options. ### Command line From ad91cdaecabfba89e1a8439db5924c0ec82cf6fd Mon Sep 17 00:00:00 2001 From: Stefanie Molin <24376333+stefmolin@users.noreply.github.com> Date: Sat, 25 Oct 2025 12:26:17 -0300 Subject: [PATCH 6/7] Update section headers for docstringify modes --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index ff8013c..7813e89 100644 --- a/README.md +++ b/README.md @@ -102,7 +102,7 @@ You can use Docstringify in three modes: > [!NOTE] > The examples in this section apply to versions 2.0.0 and greater. If you are using an older version, consult the README at that tag. -#### Check mode +#### Check mode: `docstringify-check` Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`: @@ -123,7 +123,7 @@ By default, all docstrings are required. If you want to be more lenient, you can args: [--threshold=0.75] ``` -#### Suggest mode +#### Suggest mode: `docstringify-suggest` If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), use the `suggest` mode, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `"""__description__"""`): @@ -135,7 +135,7 @@ If you would like to see suggested docstring templates (inferred from type annot args: [--style=numpydoc] ``` -#### Edit mode +#### Edit mode: `docstringify-edit` Use the `edit` mode to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html): @@ -158,7 +158,7 @@ If you want the changes to be made in place, add `--overwrite`. Here, we ask for ``` > [!WARNING] -> Make sure you only operate on files that are in version control with this setting. +> Make sure you only operate on files that are in version control if you are using `--overwrite`. Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options. From 10dc290b366bb1ec701c7517c4a055d7d01a2dd9 Mon Sep 17 00:00:00 2001 From: Stefanie Molin <24376333+stefmolin@users.noreply.github.com> Date: Sat, 25 Oct 2025 12:29:30 -0300 Subject: [PATCH 7/7] Lint --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7813e89..2e3cf6e 100644 --- a/README.md +++ b/README.md @@ -99,7 +99,7 @@ You can use Docstringify in three modes: ### Pre-commit hook -> [!NOTE] +> [!NOTE] > The examples in this section apply to versions 2.0.0 and greater. If you are using an older version, consult the README at that tag. #### Check mode: `docstringify-check`