{"id":50172432,"url":"https://github.com/stefmolin/docstringify","last_synced_at":"2026-06-10T16:00:28.226Z","repository":{"id":289532218,"uuid":"957738808","full_name":"stefmolin/docstringify","owner":"stefmolin","description":"Flag missing docstrings and, optionally, generate them from signatures and type annotations.","archived":false,"fork":false,"pushed_at":"2026-04-26T17:18:16.000Z","size":224,"stargazers_count":6,"open_issues_count":11,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-10T12:03:01.749Z","etag":null,"topics":["abstract-syntax-tree","ast","docstring","docstring-generator","google-docstring","numpydoc","pre-commit","pre-commit-hook","stubs"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/docstringify/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stefmolin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"stefmolin","buy_me_a_coffee":"stefanie.molin"}},"created_at":"2025-03-31T03:24:37.000Z","updated_at":"2026-04-26T17:18:18.000Z","dependencies_parsed_at":"2025-04-23T19:40:46.120Z","dependency_job_id":"6e3230e8-7b6e-47c5-b2e3-758c4b10bee6","html_url":"https://github.com/stefmolin/docstringify","commit_stats":null,"previous_names":["stefmolin/docstringify"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/stefmolin/docstringify","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefmolin%2Fdocstringify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefmolin%2Fdocstringify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefmolin%2Fdocstringify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefmolin%2Fdocstringify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stefmolin","download_url":"https://codeload.github.com/stefmolin/docstringify/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefmolin%2Fdocstringify/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34159251,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["abstract-syntax-tree","ast","docstring","docstring-generator","google-docstring","numpydoc","pre-commit","pre-commit-hook","stubs"],"created_at":"2026-05-25T00:00:46.386Z","updated_at":"2026-06-10T16:00:28.217Z","avatar_url":"https://github.com/stefmolin.png","language":"Python","funding_links":["https://github.com/sponsors/stefmolin","https://buymeacoffee.com/stefanie.molin"],"categories":["List of Content"],"sub_categories":["Software"],"readme":"# Docstringify\nFlag missing docstrings and, optionally, generate them from signatures and type annotations.\n\n\u003ctable\u003e\n   \u003ctr\u003e\n     \u003ctd\u003e\n      \u003cimg alt=\"Last Release\" src=\"https://img.shields.io/badge/last%20release-inactive?style=for-the-badge\"\u003e\n     \u003c/td\u003e\n     \u003ctd\u003e\n      \u003ca href=\"https://pypi.org/project/docstringify/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg alt=\"PyPI release\" src=\"https://img.shields.io/pypi/v/docstringify.svg\"\u003e\n      \u003c/a\u003e\n      \u003ca href=\"https://pypi.org/project/docstringify/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg alt=\"Supported Python Versions\" src=\"https://img.shields.io/pypi/pyversions/docstringify\"\u003e\n      \u003c/a\u003e\n      \u003ca href=\"https://github.com/stefmolin/docstringify/blob/main/LICENSE\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n         \u003cimg alt=\"License\" src=\"https://img.shields.io/pypi/l/docstringify.svg?color=blueviolet\"\u003e\n      \u003c/a\u003e\n     \u003c/td\u003e\n   \u003c/tr\u003e\n   \u003ctr\u003e\n     \u003ctd\u003e\n      \u003cimg alt=\"Build status\" src=\"https://img.shields.io/badge/build%20status-inactive?style=for-the-badge\"\u003e\n     \u003c/td\u003e\n     \u003ctd\u003e\n\u003c!--       \u003ca href=\"https://codecov.io/gh/stefmolin/docstringify\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg alt=\"codecov\" src=\"https://codecov.io/gh/stefmolin/docstringify/branch/main/graph/badge.svg?token=3SEEG9SZQO\"\u003e\n      \u003c/a\u003e --\u003e\n      \u003ca href=\"https://github.com/stefmolin/docstringify/actions/workflows/ci.yml\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg alt=\"CI\" src=\"https://github.com/stefmolin/docstringify/actions/workflows/ci.yml/badge.svg\"\u003e\n      \u003c/a\u003e\n     \u003c/td\u003e\n   \u003c/tr\u003e\n   \u003ctr\u003e\n     \u003ctd\u003e\n      \u003cimg alt=\"Downloads\" src=\"https://img.shields.io/badge/%23downloads-inactive?style=for-the-badge\"\u003e\n     \u003c/td\u003e\n     \u003ctd\u003e\n      \u003ca href=\"https://pypi.org/project/docstringify/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg alt=\"PyPI downloads\" src=\"https://img.shields.io/pepy/dt/docstringify?label=pypi\u0026color=blueviolet\"\u003e\n      \u003c/a\u003e\n     \u003c/td\u003e\n   \u003c/tr\u003e\n  \u003c/table\u003e\n\n## About\n\nGiven a file, `test.py`, with the following contents:\n\n```python\ndef say_hello(name: str = 'World') -\u003e None:\n    print(f'Hello, {name}!')\n```\n\nYou can use Docstringify in three modes:\n\n1. `check` \u0026ndash; Flag missing docstrings:\n\n    ```\n    test is missing a docstring\n    test.say_hello is missing a docstring\n    ```\n2. `suggest` \u0026ndash; Suggest docstring templates based on type annotations:\n\n    ```\n    test is missing a docstring\n    Hint:\n    \"\"\"__description__\"\"\"\n\n    test.say_hello is missing a docstring\n    Hint:\n    \"\"\"\n    __description__\n\n    Parameters\n    ----------\n    name : str, default=\"World\"\n        __description__\n    \"\"\"\n    ```\n3. `edit` \u0026ndash; Add docstring templates to source code files:\n\n    ```python\n    \"\"\"__description__\"\"\"\n\n    def say_hello(name: str = 'World') -\u003e None:\n        \"\"\"\n        __description__\n\n        Parameters\n        ----------\n        name : str, default=\"World\"\n            __description__\n        \"\"\"\n        print(f'Hello, {name}!')\n    ```\n\n## Usage\n\n### Pre-commit hook\n\n\u003e [!NOTE]\n\u003e 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.\n\n#### Check mode: `docstringify-check`\n\nAdd the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`:\n\n```yaml\n- repo: https://github.com/stefmolin/docstringify\n  rev: \u003cversion\u003e\n  hooks:\n    - id: docstringify-check\n```\n\nBy 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:\n\n```yaml\n- repo: https://github.com/stefmolin/docstringify\n  rev: \u003cversion\u003e\n  hooks:\n    - id: docstringify-check\n      args: [--threshold=0.75]\n```\n\n#### Suggest mode: `docstringify-suggest`\n\nIf 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__\"\"\"`):\n\n```yaml\n- repo: https://github.com/stefmolin/docstringify\n  rev: \u003cversion\u003e\n  hooks:\n    - id: docstringify-suggest\n      args: [--style=stub]\n```\n\n#### Edit mode: `docstringify-edit`\n\nUse 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):\n\n```yaml\n- repo: https://github.com/stefmolin/docstringify\n  rev: \u003cversion\u003e\n  hooks:\n    - id: docstringify-edit\n      args: [--style=google]\n```\n\nIf 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:\n\n```yaml\n- repo: https://github.com/stefmolin/docstringify\n  rev: \u003cversion\u003e\n  hooks:\n    - id: docstringify-edit\n      args: [--overwrite, --style=numpydoc]\n```\n\n\u003e [!WARNING]\n\u003e Make sure you only operate on files that are in version control if you are using `--overwrite`.\n\nBe sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.\n\n### Command line\n\nFirst, install the `docstringify` package from PyPI:\n\n```shell\n$ python -m pip install docstringify\n```\n\nThen, use the `docstringify` entry point on the file(s) of your choice. For example, to run in `check` mode:\n\n```shell\n$ docstringify check /path/to/file [/path/to/another/file]\n```\n\nRun `docstringify --help` for more information.\n\n### Python\n\nFirst, install the `docstringify` package from PyPI:\n\n```shell\n$ python -m pip install docstringify\n```\n\nThen, use the `DocstringVisitor()` class on individual files to see spots where docstrings are missing:\n\n```pycon\n\u003e\u003e\u003e from docstringify.traversal import DocstringVisitor\n\u003e\u003e\u003e visitor = DocstringVisitor('test.py')\n\u003e\u003e\u003e visitor.process_file()\ntest is missing a docstring\ntest.say_hello is missing a docstring\n```\n\nIf you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide a converter:\n\n```pycon\n\u003e\u003e\u003e from docstringify.converters import NumpydocDocstringConverter\n\u003e\u003e\u003e from docstringify.traversal import DocstringVisitor\n\u003e\u003e\u003e visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)\n\u003e\u003e\u003e visitor.process_file()\ntest is missing a docstring\nHint:\n\"\"\"__description__\"\"\"\n\ntest.say_hello is missing a docstring\nHint:\n\"\"\"\n__description__\n\nParameters\n----------\nname : str, default=\"World\"\n    __description__\n\"\"\"\n\n```\n\nTo make changes to your files, you will need to use the `DocstringTransformer` instead. With the `DocstringTransformer`, the converter is required:\n\n```pycon\n\u003e\u003e\u003e from docstringify.converters import GoogleDocstringConverter\n\u003e\u003e\u003e from docstringify.traversal import DocstringTransformer\n\u003e\u003e\u003e transformer = DocstringTransformer('test.py', converter=GoogleDocstringConverter)\n\u003e\u003e\u003e transformer.process_file()\ntest is missing a docstring\ntest.say_hello is missing a docstring\nDocstring templates written to /.../test_docstringify.py\n```\n\nIf you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`:\n\n```pycon\n\u003e\u003e\u003e from docstringify.converters import GoogleDocstringConverter\n\u003e\u003e\u003e from docstringify.traversal import DocstringTransformer\n\u003e\u003e\u003e transformer = DocstringTransformer(\n...     'test.py', converter=GoogleDocstringConverter, overwrite=True\n... )\n\u003e\u003e\u003e transformer.process_file()\ntest is missing a docstring\ntest.say_hello is missing a docstring\nDocstring templates written to /.../test.py\n```\n\n## Contributing\n\nPlease consult the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefmolin%2Fdocstringify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstefmolin%2Fdocstringify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefmolin%2Fdocstringify/lists"}