diff --git a/README.md b/README.md index c62c4ed..2e3cf6e 100644 --- a/README.md +++ b/README.md @@ -54,12 +54,14 @@ 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 +78,8 @@ 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__""" @@ -96,55 +99,67 @@ 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. + +#### 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`: ```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__"""`): +#### 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__"""`): ```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): +#### 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): ```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`. 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] ``` +> [!WARNING] +> 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. ### Command line @@ -155,10 +170,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. 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]