docstringify 1.1.1__tar.gz → 2.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. {docstringify-1.1.1 → docstringify-2.0.0}/.github/dependabot.yml +4 -2
  2. {docstringify-1.1.1 → docstringify-2.0.0}/.github/workflows/ci.yml +12 -5
  3. {docstringify-1.1.1 → docstringify-2.0.0}/.github/workflows/greetings.yml +4 -4
  4. {docstringify-1.1.1 → docstringify-2.0.0}/.github/workflows/pypi-publish.yml +9 -9
  5. {docstringify-1.1.1 → docstringify-2.0.0}/.pre-commit-config.yaml +21 -7
  6. docstringify-2.0.0/.pre-commit-hooks.yaml +36 -0
  7. {docstringify-1.1.1 → docstringify-2.0.0}/PKG-INFO +81 -25
  8. {docstringify-1.1.1 → docstringify-2.0.0}/README.md +78 -21
  9. {docstringify-1.1.1 → docstringify-2.0.0}/pyproject.toml +17 -16
  10. docstringify-2.0.0/src/docstringify/cli.py +237 -0
  11. docstringify-2.0.0/src/docstringify/converters/__init__.py +26 -0
  12. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/nodes/base.py +4 -1
  13. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/nodes/function.py +2 -1
  14. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/traversal/visitor.py +5 -5
  15. {docstringify-1.1.1 → docstringify-2.0.0}/uv.lock +2 -85
  16. docstringify-1.1.1/.pre-commit-hooks.yaml +0 -8
  17. docstringify-1.1.1/src/docstringify/cli.py +0 -128
  18. docstringify-1.1.1/src/docstringify/converters/__init__.py +0 -13
  19. {docstringify-1.1.1 → docstringify-2.0.0}/.github/ISSUE_TEMPLATE/bug_report.md +0 -0
  20. {docstringify-1.1.1 → docstringify-2.0.0}/.github/ISSUE_TEMPLATE/feature_request.md +0 -0
  21. {docstringify-1.1.1 → docstringify-2.0.0}/.github/pull_request_template.md +0 -0
  22. {docstringify-1.1.1 → docstringify-2.0.0}/.github/release.yml +0 -0
  23. {docstringify-1.1.1 → docstringify-2.0.0}/.gitignore +0 -0
  24. {docstringify-1.1.1 → docstringify-2.0.0}/.python-version +0 -0
  25. {docstringify-1.1.1 → docstringify-2.0.0}/CODE_OF_CONDUCT.md +0 -0
  26. {docstringify-1.1.1 → docstringify-2.0.0}/CONTRIBUTING.md +0 -0
  27. {docstringify-1.1.1 → docstringify-2.0.0}/LICENSE +0 -0
  28. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/__init__.py +0 -0
  29. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/__main__.py +0 -0
  30. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/components.py +0 -0
  31. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/converters/base.py +0 -0
  32. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/converters/google.py +0 -0
  33. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/converters/numpydoc.py +0 -0
  34. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/converters/stub.py +0 -0
  35. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/exceptions.py +0 -0
  36. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/nodes/__init__.py +0 -0
  37. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/traversal/__init__.py +0 -0
  38. {docstringify-1.1.1 → docstringify-2.0.0}/src/docstringify/traversal/transformer.py +0 -0
{docstringify-1.1.1 → docstringify-2.0.0}/.github/dependabot.yml RENAMED
@@ -7,8 +7,10 @@ updates:
7
7
  - package-ecosystem: "github-actions"
8
8
  directory: "/"
9
9
  schedule:
10
- # Check for updates to GitHub Actions every month
11
- interval: "monthly"
10
+ interval: "quarterly"
11
+ ignore: # only update minor or major version changes
12
+ - dependency-name: "*"
13
+ update-types: ["version-update:semver-patch"]
12
14
  groups:
13
15
  actions:
14
16
  patterns:
{docstringify-1.1.1 → docstringify-2.0.0}/.github/workflows/ci.yml RENAMED
@@ -43,13 +43,13 @@ jobs:
43
43
  fail-fast: false
44
44
  matrix:
45
45
  os: [macos-latest, ubuntu-latest, windows-latest]
46
- python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
46
+ python-version: ["3.11", "3.12", "3.13", "3.14"]
47
47
 
48
48
  steps:
49
- - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
49
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
50
50
 
51
51
  - name: Set up Python ${{ matrix.python-version }}
52
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
52
+ uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
53
53
  with:
54
54
  python-version: ${{ matrix.python-version }}
55
55
 
@@ -65,5 +65,12 @@ jobs:
65
65
  - name: Install dev dependencies
66
66
  run: python -m pip install --group dev
67
67
 
68
- - name: Validate pre-commit hook
69
- run: pre-commit try-repo . docstringify
68
+ - name: Check that the docstringify-edit pre-commit hook is available
69
+ run: pre-commit try-repo . docstringify-edit
70
+
71
+ - name: Check that the docstringify-suggest pre-commit hook is available
72
+ run: pre-commit try-repo . docstringify-suggest
73
+
74
+ # this is the only hook that works without an additional arg so we can test it like this
75
+ - name: Validate the docstringify-check pre-commit hook
76
+ run: pre-commit try-repo . docstringify-check --all-files
{docstringify-1.1.1 → docstringify-2.0.0}/.github/workflows/greetings.yml RENAMED
@@ -9,8 +9,8 @@ jobs:
9
9
  issues: write
10
10
  pull-requests: write
11
11
  steps:
12
- - uses: actions/first-interaction@34f15e814fe48ac9312ccf29db4e74fa767cbab7 # v1.3.0
12
+ - uses: actions/first-interaction@1c4688942c71f71d4f5502a26ea67c331730fa4d # v3.1.0
13
13
  with:
14
- repo-token: ${{ secrets.GITHUB_TOKEN }}
15
- issue-message: "It looks like this is your first issue here – welcome! Please familiarize yourself with the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md), if you haven't already."
16
- pr-message: "Congratulations on making your first pull request to `docstringify`! Please familiarize yourself with the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md), if you haven't already."
14
+ repo_token: ${{ secrets.GITHUB_TOKEN }}
15
+ issue_message: "It looks like this is your first issue here – welcome! Please familiarize yourself with the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md), if you haven't already."
16
+ pr_message: "Congratulations on making your first pull request to `docstringify`! Please familiarize yourself with the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md), if you haven't already."
{docstringify-1.1.1 → docstringify-2.0.0}/.github/workflows/pypi-publish.yml RENAMED
@@ -10,9 +10,9 @@ jobs:
10
10
  runs-on: ubuntu-latest
11
11
 
12
12
  steps:
13
- - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
13
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
14
14
  - name: Set up Python
15
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
15
+ uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
16
16
  with:
17
17
  python-version: "3.x"
18
18
  - name: Install pypa/build
@@ -24,7 +24,7 @@ jobs:
24
24
  - name: Build a binary wheel and a source tarball
25
25
  run: python3 -m build
26
26
  - name: Store the distribution packages
27
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
27
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
28
28
  with:
29
29
  name: python-package-distributions
30
30
  path: dist/
@@ -44,12 +44,12 @@ jobs:
44
44
 
45
45
  steps:
46
46
  - name: Download all the dists
47
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
47
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
48
48
  with:
49
49
  name: python-package-distributions
50
50
  path: dist/
51
51
  - name: Publish distribution 📦 to PyPI
52
- uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
52
+ uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
53
53
 
54
54
  github-release:
55
55
  name: >-
@@ -65,12 +65,12 @@ jobs:
65
65
 
66
66
  steps:
67
67
  - name: Download all the dists
68
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
68
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
69
69
  with:
70
70
  name: python-package-distributions
71
71
  path: dist/
72
72
  - name: Sign the dists with Sigstore
73
- uses: sigstore/gh-action-sigstore-python@f514d46b907ebcd5bedc05145c03b69c1edd8b46 # v3.0.0
73
+ uses: sigstore/gh-action-sigstore-python@04cffa1d795717b140764e8b640de88853c92acc # v3.3.0
74
74
  with:
75
75
  inputs: >-
76
76
  ./dist/*.tar.gz
@@ -110,11 +110,11 @@ jobs:
110
110
 
111
111
  steps:
112
112
  - name: Download all the dists
113
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
113
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
114
114
  with:
115
115
  name: python-package-distributions
116
116
  path: dist/
117
117
  - name: Publish distribution 📦 to TestPyPI
118
- uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
118
+ uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
119
119
  with:
120
120
  repository-url: https://test.pypi.org/legacy/
{docstringify-1.1.1 → docstringify-2.0.0}/.pre-commit-config.yaml RENAMED
@@ -4,34 +4,48 @@ ci:
4
4
 
5
5
  repos:
6
6
  - repo: https://github.com/pre-commit/pre-commit-hooks
7
- rev: v5.0.0
7
+ rev: v6.0.0
8
8
  hooks:
9
9
  - id: check-toml
10
10
  - id: check-yaml
11
11
  - id: end-of-file-fixer
12
12
  - id: trailing-whitespace
13
13
 
14
+ - repo: https://github.com/codespell-project/codespell
15
+ rev: v2.4.2
16
+ hooks:
17
+ - id: codespell
18
+ additional_dependencies:
19
+ - tomli
20
+ exclude: (\.(svg|png|pdf)$)|(CODE_OF_CONDUCT.md)
21
+
14
22
  - repo: https://github.com/numpy/numpydoc
15
- rev: v1.9.0
23
+ rev: v1.10.0
16
24
  hooks:
17
25
  - id: numpydoc-validation
18
26
  exclude: (tests|docs)/.*
19
27
 
20
28
  - repo: https://github.com/stefmolin/docstringify
21
- rev: 1.0.0
29
+ rev: 1decb1a66b512ab792fdc0d190a7ba761b3d70fd
22
30
  hooks:
23
- - id: docstringify
24
- args: [--make-changes-inplace=numpydoc]
31
+ - id: docstringify-edit
32
+ name: docstringify source code with numpydoc style
33
+ args: [--overwrite, --style=numpydoc]
34
+ files: src/.*
35
+ - id: docstringify-edit
36
+ name: docstringify tests with stubs
37
+ args: [--overwrite, --style=stub]
38
+ files: tests/.*
25
39
 
26
40
  - repo: https://github.com/astral-sh/ruff-pre-commit
27
- rev: v0.12.2
41
+ rev: v0.15.12
28
42
  hooks:
29
43
  - id: ruff-check
30
44
  args: [--fix, --exit-non-zero-on-fix, --show-fixes]
31
45
  - id: ruff-format
32
46
 
33
47
  - repo: https://github.com/tox-dev/pyproject-fmt
34
- rev: v2.6.0
48
+ rev: v2.21.1
35
49
  hooks:
36
50
  - id: pyproject-fmt
37
51
  args: [--keep-full-version, --no-print-diff]
docstringify-2.0.0/.pre-commit-hooks.yaml ADDED
@@ -0,0 +1,36 @@
1
+ - id: docstringify-edit
2
+ name: generate missing docstrings with docstringify
3
+ description: >-
4
+ Generate missing docstrings from signatures and type annotations,
5
+ injecting them into the source code.
6
+ entry: docstringify edit
7
+ language: python
8
+ types: [python]
9
+
10
+ - id: docstringify-suggest
11
+ name: suggest docstrings with docstringify
12
+ description: >-
13
+ Generate suggestions for missing docstrings from signatures and
14
+ type annotations, printing them for inspection.
15
+ entry: docstringify suggest
16
+ language: python
17
+ types: [python]
18
+
19
+ - id: docstringify-check
20
+ name: check for missing docstrings with docstringify
21
+ description: >-
22
+ Flag missing docstrings, failing if more than the threshold are missing.
23
+ entry: docstringify check
24
+ language: python
25
+ require_serial: true
26
+ types: [python]
27
+
28
+ - id: docstringify
29
+ name: docstringify (deprecated)
30
+ description: >-
31
+ Flag missing docstrings and, optionally, generate them from signatures
32
+ and type annotations.
33
+ entry: docstringify
34
+ language: python
35
+ require_serial: true
36
+ types: [python]
{docstringify-1.1.1 → docstringify-2.0.0}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: docstringify
3
- Version: 1.1.1
3
+ Version: 2.0.0
4
4
  Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
5
5
  Project-URL: Documentation, https://github.com/stefmolin/docstringify
6
6
  Project-URL: Homepage, https://github.com/stefmolin/docstringify
@@ -12,17 +12,58 @@ Keywords: ast,docstring generation,google-style docstring,numpydoc-style docstri
12
12
  Classifier: Development Status :: 4 - Beta
13
13
  Classifier: Programming Language :: Python
14
14
  Classifier: Programming Language :: Python :: 3 :: Only
15
- Classifier: Programming Language :: Python :: 3.9
16
- Classifier: Programming Language :: Python :: 3.10
17
15
  Classifier: Programming Language :: Python :: 3.11
18
16
  Classifier: Programming Language :: Python :: 3.12
19
17
  Classifier: Programming Language :: Python :: 3.13
20
- Requires-Python: >=3.9
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Requires-Python: >=3.11
21
20
  Description-Content-Type: text/markdown
22
21
 
23
22
  # Docstringify
24
23
  Flag missing docstrings and, optionally, generate them from signatures and type annotations.
25
24
 
25
+ <table>
26
+ <tr>
27
+ <td>
28
+ <img alt="Last Release" src="https://img.shields.io/badge/last%20release-inactive?style=for-the-badge">
29
+ </td>
30
+ <td>
31
+ <a href="https://pypi.org/project/docstringify/" target="_blank" rel="noopener noreferrer">
32
+ <img alt="PyPI release" src="https://img.shields.io/pypi/v/docstringify.svg">
33
+ </a>
34
+ <a href="https://pypi.org/project/docstringify/" target="_blank" rel="noopener noreferrer">
35
+ <img alt="Supported Python Versions" src="https://img.shields.io/pypi/pyversions/docstringify">
36
+ </a>
37
+ <a href="https://github.com/stefmolin/docstringify/blob/main/LICENSE" target="_blank" rel="noopener noreferrer">
38
+ <img alt="License" src="https://img.shields.io/pypi/l/docstringify.svg?color=blueviolet">
39
+ </a>
40
+ </td>
41
+ </tr>
42
+ <tr>
43
+ <td>
44
+ <img alt="Build status" src="https://img.shields.io/badge/build%20status-inactive?style=for-the-badge">
45
+ </td>
46
+ <td>
47
+ <!-- <a href="https://codecov.io/gh/stefmolin/docstringify" target="_blank" rel="noopener noreferrer">
48
+ <img alt="codecov" src="https://codecov.io/gh/stefmolin/docstringify/branch/main/graph/badge.svg?token=3SEEG9SZQO">
49
+ </a> -->
50
+ <a href="https://github.com/stefmolin/docstringify/actions/workflows/ci.yml" target="_blank" rel="noopener noreferrer">
51
+ <img alt="CI" src="https://github.com/stefmolin/docstringify/actions/workflows/ci.yml/badge.svg">
52
+ </a>
53
+ </td>
54
+ </tr>
55
+ <tr>
56
+ <td>
57
+ <img alt="Downloads" src="https://img.shields.io/badge/%23downloads-inactive?style=for-the-badge">
58
+ </td>
59
+ <td>
60
+ <a href="https://pypi.org/project/docstringify/" target="_blank" rel="noopener noreferrer">
61
+ <img alt="PyPI downloads" src="https://img.shields.io/pepy/dt/docstringify?label=pypi&color=blueviolet">
62
+ </a>
63
+ </td>
64
+ </tr>
65
+ </table>
66
+
26
67
  ## About
27
68
 
28
69
  Given a file, `test.py`, with the following contents:
@@ -34,12 +75,14 @@ def say_hello(name: str = 'World') -> None:
34
75
 
35
76
  You can use Docstringify in three modes:
36
77
 
37
- 1. Flag missing docstrings:
78
+ 1. `check` &ndash; Flag missing docstrings:
79
+
38
80
  ```
39
81
  test is missing a docstring
40
82
  test.say_hello is missing a docstring
41
83
  ```
42
- 2. Suggest docstring templates based on type annotations:
84
+ 2. `suggest` &ndash; Suggest docstring templates based on type annotations:
85
+
43
86
  ```
44
87
  test is missing a docstring
45
88
  Hint:
@@ -56,7 +99,8 @@ You can use Docstringify in three modes:
56
99
  __description__
57
100
  """
58
101
  ```
59
- 3. Add docstring templates to source code files:
102
+ 3. `edit` &ndash; Add docstring templates to source code files:
103
+
60
104
  ```python
61
105
  """__description__"""
62
106
 
@@ -76,55 +120,67 @@ You can use Docstringify in three modes:
76
120
 
77
121
  ### Pre-commit hook
78
122
 
123
+ > [!NOTE]
124
+ > 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.
125
+
126
+ #### Check mode: `docstringify-check`
127
+
79
128
  Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`:
80
129
 
81
130
  ```yaml
82
131
  - repo: https://github.com/stefmolin/docstringify
83
- rev: 1.1.0
132
+ rev: <version>
84
133
  hooks:
85
- - id: docstringify
134
+ - id: docstringify-check
86
135
  ```
87
136
 
88
137
  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:
89
138
 
90
139
  ```yaml
91
140
  - repo: https://github.com/stefmolin/docstringify
92
- rev: 1.1.0
141
+ rev: <version>
93
142
  hooks:
94
- - id: docstringify
143
+ - id: docstringify-check
95
144
  args: [--threshold=0.75]
96
145
  ```
97
146
 
98
- 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__"""`):
147
+ #### Suggest mode: `docstringify-suggest`
148
+
149
+ 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__"""`):
99
150
 
100
151
  ```yaml
101
152
  - repo: https://github.com/stefmolin/docstringify
102
- rev: 1.1.0
153
+ rev: <version>
103
154
  hooks:
104
- - id: docstringify
105
- args: [--suggest-changes=numpydoc]
155
+ - id: docstringify-suggest
156
+ args: [--style=stub]
106
157
  ```
107
158
 
108
- 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):
159
+ #### Edit mode: `docstringify-edit`
160
+
161
+ 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):
109
162
 
110
163
  ```yaml
111
164
  - repo: https://github.com/stefmolin/docstringify
112
- rev: 1.1.0
165
+ rev: <version>
113
166
  hooks:
114
- - id: docstringify
115
- args: [--make-changes=google]
167
+ - id: docstringify-edit
168
+ args: [--style=google]
116
169
  ```
117
170
 
118
- If you want the changes to be made in place, change `--make-changes` to `--make-changes-inplace` &ndash; 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:
171
+ 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:
119
172
 
120
173
  ```yaml
121
174
  - repo: https://github.com/stefmolin/docstringify
122
- rev: 1.1.0
175
+ rev: <version>
123
176
  hooks:
124
- - id: docstringify
125
- args: [--make-changes-inplace=numpydoc]
177
+ - id: docstringify-edit
178
+ args: [--overwrite, --style=numpydoc]
126
179
  ```
127
180
 
181
+ > [!WARNING]
182
+ > Make sure you only operate on files that are in version control if you are using `--overwrite`.
183
+
128
184
  Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
129
185
 
130
186
  ### Command line
@@ -135,10 +191,10 @@ First, install the `docstringify` package from PyPI:
135
191
  $ python -m pip install docstringify
136
192
  ```
137
193
 
138
- Then, use the `docstringify` entry point on the file(s) of your choice:
194
+ Then, use the `docstringify` entry point on the file(s) of your choice. For example, to run in `check` mode:
139
195
 
140
196
  ```shell
141
- $ docstringify /path/to/file [/path/to/another/file]
197
+ $ docstringify check /path/to/file [/path/to/another/file]
142
198
  ```
143
199
 
144
200
  Run `docstringify --help` for more information.
{docstringify-1.1.1 → docstringify-2.0.0}/README.md RENAMED
@@ -1,6 +1,48 @@
1
1
  # Docstringify
2
2
  Flag missing docstrings and, optionally, generate them from signatures and type annotations.
3
3
 
4
+ <table>
5
+ <tr>
6
+ <td>
7
+ <img alt="Last Release" src="https://img.shields.io/badge/last%20release-inactive?style=for-the-badge">
8
+ </td>
9
+ <td>
10
+ <a href="https://pypi.org/project/docstringify/" target="_blank" rel="noopener noreferrer">
11
+ <img alt="PyPI release" src="https://img.shields.io/pypi/v/docstringify.svg">
12
+ </a>
13
+ <a href="https://pypi.org/project/docstringify/" target="_blank" rel="noopener noreferrer">
14
+ <img alt="Supported Python Versions" src="https://img.shields.io/pypi/pyversions/docstringify">
15
+ </a>
16
+ <a href="https://github.com/stefmolin/docstringify/blob/main/LICENSE" target="_blank" rel="noopener noreferrer">
17
+ <img alt="License" src="https://img.shields.io/pypi/l/docstringify.svg?color=blueviolet">
18
+ </a>
19
+ </td>
20
+ </tr>
21
+ <tr>
22
+ <td>
23
+ <img alt="Build status" src="https://img.shields.io/badge/build%20status-inactive?style=for-the-badge">
24
+ </td>
25
+ <td>
26
+ <!-- <a href="https://codecov.io/gh/stefmolin/docstringify" target="_blank" rel="noopener noreferrer">
27
+ <img alt="codecov" src="https://codecov.io/gh/stefmolin/docstringify/branch/main/graph/badge.svg?token=3SEEG9SZQO">
28
+ </a> -->
29
+ <a href="https://github.com/stefmolin/docstringify/actions/workflows/ci.yml" target="_blank" rel="noopener noreferrer">
30
+ <img alt="CI" src="https://github.com/stefmolin/docstringify/actions/workflows/ci.yml/badge.svg">
31
+ </a>
32
+ </td>
33
+ </tr>
34
+ <tr>
35
+ <td>
36
+ <img alt="Downloads" src="https://img.shields.io/badge/%23downloads-inactive?style=for-the-badge">
37
+ </td>
38
+ <td>
39
+ <a href="https://pypi.org/project/docstringify/" target="_blank" rel="noopener noreferrer">
40
+ <img alt="PyPI downloads" src="https://img.shields.io/pepy/dt/docstringify?label=pypi&color=blueviolet">
41
+ </a>
42
+ </td>
43
+ </tr>
44
+ </table>
45
+
4
46
  ## About
5
47
 
6
48
  Given a file, `test.py`, with the following contents:
@@ -12,12 +54,14 @@ def say_hello(name: str = 'World') -> None:
12
54
 
13
55
  You can use Docstringify in three modes:
14
56
 
15
- 1. Flag missing docstrings:
57
+ 1. `check` &ndash; Flag missing docstrings:
58
+
16
59
  ```
17
60
  test is missing a docstring
18
61
  test.say_hello is missing a docstring
19
62
  ```
20
- 2. Suggest docstring templates based on type annotations:
63
+ 2. `suggest` &ndash; Suggest docstring templates based on type annotations:
64
+
21
65
  ```
22
66
  test is missing a docstring
23
67
  Hint:
@@ -34,7 +78,8 @@ You can use Docstringify in three modes:
34
78
  __description__
35
79
  """
36
80
  ```
37
- 3. Add docstring templates to source code files:
81
+ 3. `edit` &ndash; Add docstring templates to source code files:
82
+
38
83
  ```python
39
84
  """__description__"""
40
85
 
@@ -54,55 +99,67 @@ You can use Docstringify in three modes:
54
99
 
55
100
  ### Pre-commit hook
56
101
 
102
+ > [!NOTE]
103
+ > 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.
104
+
105
+ #### Check mode: `docstringify-check`
106
+
57
107
  Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`:
58
108
 
59
109
  ```yaml
60
110
  - repo: https://github.com/stefmolin/docstringify
61
- rev: 1.1.0
111
+ rev: <version>
62
112
  hooks:
63
- - id: docstringify
113
+ - id: docstringify-check
64
114
  ```
65
115
 
66
116
  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:
67
117
 
68
118
  ```yaml
69
119
  - repo: https://github.com/stefmolin/docstringify
70
- rev: 1.1.0
120
+ rev: <version>
71
121
  hooks:
72
- - id: docstringify
122
+ - id: docstringify-check
73
123
  args: [--threshold=0.75]
74
124
  ```
75
125
 
76
- 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__"""`):
126
+ #### Suggest mode: `docstringify-suggest`
127
+
128
+ 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__"""`):
77
129
 
78
130
  ```yaml
79
131
  - repo: https://github.com/stefmolin/docstringify
80
- rev: 1.1.0
132
+ rev: <version>
81
133
  hooks:
82
- - id: docstringify
83
- args: [--suggest-changes=numpydoc]
134
+ - id: docstringify-suggest
135
+ args: [--style=stub]
84
136
  ```
85
137
 
86
- 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):
138
+ #### Edit mode: `docstringify-edit`
139
+
140
+ 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):
87
141
 
88
142
  ```yaml
89
143
  - repo: https://github.com/stefmolin/docstringify
90
- rev: 1.1.0
144
+ rev: <version>
91
145
  hooks:
92
- - id: docstringify
93
- args: [--make-changes=google]
146
+ - id: docstringify-edit
147
+ args: [--style=google]
94
148
  ```
95
149
 
96
- If you want the changes to be made in place, change `--make-changes` to `--make-changes-inplace` &ndash; 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:
150
+ 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:
97
151
 
98
152
  ```yaml
99
153
  - repo: https://github.com/stefmolin/docstringify
100
- rev: 1.1.0
154
+ rev: <version>
101
155
  hooks:
102
- - id: docstringify
103
- args: [--make-changes-inplace=numpydoc]
156
+ - id: docstringify-edit
157
+ args: [--overwrite, --style=numpydoc]
104
158
  ```
105
159
 
160
+ > [!WARNING]
161
+ > Make sure you only operate on files that are in version control if you are using `--overwrite`.
162
+
106
163
  Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
107
164
 
108
165
  ### Command line
@@ -113,10 +170,10 @@ First, install the `docstringify` package from PyPI:
113
170
  $ python -m pip install docstringify
114
171
  ```
115
172
 
116
- Then, use the `docstringify` entry point on the file(s) of your choice:
173
+ Then, use the `docstringify` entry point on the file(s) of your choice. For example, to run in `check` mode:
117
174
 
118
175
  ```shell
119
- $ docstringify /path/to/file [/path/to/another/file]
176
+ $ docstringify check /path/to/file [/path/to/another/file]
120
177
  ```
121
178
 
122
179
  Run `docstringify --help` for more information.