docstring-tailor 0.3.1__tar.gz → 0.4.1__tar.gz

{docstring_tailor-0.3.1 → docstring_tailor-0.4.1}/.gitignore

@@ -55,6 +55,4 @@ Desktop.ini
 *.swo
 
 # Project-specific
-bitmaps/.~lock*
-bitmaps/.~lock.*#
 **/readme.todo

docstring_tailor-0.4.1/.pre-commit-hooks.yaml

@@ -0,0 +1,8 @@
+# Hook definition consumed via `repo: https://github.com/AukeB/docstring-tailor`.
+# Consumers must supply the style through `args`, e.g. args: ["style", "google"].
+- id: docstring-tailor
+  name: docstring-tailor
+  description: Format Python docstrings to a configurable line length and style.
+  entry: docstring_tailor format
+  language: python
+  types: [python]

{docstring_tailor-0.3.1 → docstring_tailor-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: docstring-tailor
-Version: 0.3.1
+Version: 0.4.1
 Summary: Formats Python docstrings to PEP 257 style with configurable line length.
 Author-email: Auke Bruinsma <afbruinsma@gmail.com>
 License: MIT License
@@ -44,16 +44,17 @@ Formats Python docstrings to PEP 257 style with configurable line length.
 ## Table of Contents
 1. [Demo](#demo)
 2. [Installation](#Installation)
-3. [Quick start](#quick_start)
+3. [Quick start](#quick-start)
 4. [API Overview](#api-overview)
     - [Command](#command)
     - [Options](#options)
     - [Examples](#examples)
-5. [Example docstrings](#example-docstrings)
-6. [What Your Line Length Says About You!](#what-your-line-length-says-about-you)
-7. [Resources](#resources)
-8. [Release Notes](#release_notes)
-9. [Roadmap](#roadmap)
+5. [Pre-commit and prek hook](#pre-commit-and-prek-hook)
+6. [Example docstrings](#example-docstrings)
+7. [What Your Line Length Says About You!](#what-your-line-length-says-about-you)
+8. [Resources](#resources)
+9. [Release Notes](#release-notes)
+10. [Roadmap](#roadmap)
 
 ## Demo
 
@@ -116,7 +117,7 @@ line-length = 88
 line-length = 88
 ```
 
-Define a docstring style. Two styles are currently supported: [Google](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) and [NumPy](https://numpydoc.readthedocs.io/en/latest/format.html). Google is the default. Explicit configuration:
+Define a docstring style. Three styles are currently supported: [Google](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html), [NumPy](https://numpydoc.readthedocs.io/en/latest/format.html), and [Sphinx](https://www.sphinx-doc.org/en/master/usage/domains/python.html#info-field-lists). The style always has to be configured explicitly.
 
 ```bash
 uv run docstring_tailor format --style numpy
@@ -135,6 +136,8 @@ To convert existing docstrings from one style to another, use the `convert` comm
 uv run docstring_tailor convert my_file.py --from-style google --to-style numpy
 ```
 
+`docstring-tailor` can also run as a [pre-commit](https://pre-commit.com/) / [prek](https://github.com/j178/prek) hook so docstrings stay formatted on every commit, see [Pre-commit and prek hook](#pre-commit-and-prek-hook).
+
 ## API Overview
 
 ### Commands
@@ -165,20 +168,20 @@ If no paths are provided, `docstring_tailor` will attempt to locate and format f
 
 | <div style="width:140px">Option</div> | <div style="width:50px">Type</div> | <div style="width:80px">Default</div> | Description |
 |---|---|---|---|
-| `--line-length`      | `int`  | 100    | Maximum number of characters allowed per line after formatting. |
-| `--style`            | `str`  | google | Docstring style to format to. `google` or `numpy`. |
-| `--exclude`          | `str`  | —      | A glob pattern for paths to exclude. Can be passed multiple times. Single-path patterns (e.g. `tests`, `*.pyi`) match by name anywhere in the tree. Relative patterns (e.g. `src/generated/*.py`) match against the path relative to the project root. |
-| `--diff`             | flag   | —      | Print a unified diff of changes to stdout instead of modifying files. No files are written when this flag is set. |
+| `--line-length`      | `int`  | 100        | Maximum number of characters allowed per line after formatting. |
+| `--style`            | `str`  | *required* | Docstring style to format to. `google`, `numpy` or `sphinx`. |
+| `--exclude`          | `str`  | —          | A glob pattern for paths to exclude. Can be passed multiple times. Single-path patterns (e.g. `tests`, `*.pyi`) match by name anywhere in the tree. Relative patterns (e.g. `src/generated/*.py`) match against the path relative to the project root. |
+| `--diff`             | flag   | —          | Print a unified diff of changes to stdout instead of modifying files. No files are written when this flag is set. |
 
 #### `convert`
 
 | <div style="width:140px">Option</div> | <div style="width:50px">Type</div> | <div style="width:80px">Default</div> | Description |
 |---|---|---|---|
-| `--from-style`       | `str`  | *required* | Docstring style to convert from. `google` or `numpy`. |
-| `--to-style`         | `str`  | *required* | Docstring style to convert to. `google` or `numpy`. Must differ from `--from-style`. |
-| `--line-length`      | `int`  | 100    | Maximum number of characters allowed per line after formatting. |
-| `--exclude`          | `str`  | —      | A glob pattern for paths to exclude. Can be passed multiple times. Single-path patterns (e.g. `tests`, `*.pyi`) match by name anywhere in the tree. Relative patterns (e.g. `src/generated/*.py`) match against the path relative to the project root. |
-| `--diff`             | flag   | —      | Print a unified diff of changes to stdout instead of modifying files. No files are written when this flag is set. |
+| `--from-style`       | `str`  | *required* | Docstring style to convert from. `google`, `numpy` or `sphinx`. |
+| `--to-style`         | `str`  | *required* | Docstring style to convert to. `google`, `numpy` or `sphinx`. Must differ from `--from-style`. |
+| `--line-length`      | `int`  | 100        | Maximum number of characters allowed per line after formatting. |
+| `--exclude`          | `str`  | —          | A glob pattern for paths to exclude. Can be passed multiple times. Single-path patterns (e.g. `tests`, `*.pyi`) match by name anywhere in the tree. Relative patterns (e.g. `src/generated/*.py`) match against the path relative to the project root. |
+| `--diff`             | flag   | —          | Print a unified diff of changes to stdout instead of modifying files. No files are written when this flag is set. |
 
 `--from-style` and `--to-style` have no config-file or default fallback — both must be given explicitly on every `convert` invocation, and must be different from each other.
 
@@ -217,6 +220,56 @@ style = "google"
 exclude = ["tests", "src/generated/*.py"]
 ```
 
+## Pre-commit and prek hook
+
+`docstring-tailor` can run as a [pre-commit](https://pre-commit.com/) hook, and works unchanged with [prek](https://github.com/j178/prek), the drop-in reimplementation, so docstrings stay formatted automatically on every commit. When the hook reformats a file it rewrites it in place and stops the commit so you can review and re-stage the change, exactly like the Ruff or Black hooks.
+
+### Hosted hook
+
+Add the following to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/AukeB/docstring-tailor
+    rev: 0.4.1
+    hooks:
+      - id: docstring-tailor
+        args: ["--style", "google"]
+```
+
+- `--style` is required, use `google`, `numpy` or `sphinx`. Pass any other option (`--line-length`, `--exclude`) through `args`, or set them in a `[tool.docstring_tailor]` config block instead. `args` is a single flat list where every flag and every value is its own quoted element (e.g. `["--style", "google", "--line-length", "88"]`, with numbers quoted). Install the hook once with `pre-commit install` (or `prek install`).
+
+Prefer TOML? prek also reads a native `prek.toml`, a drop-in alternative to `.pre-commit-config.yaml` (upstream `pre-commit` ignores it). The same hook in `prek.toml`
+
+```toml
+[[repos]]
+repo = "https://github.com/AukeB/docstring-tailor"
+rev = "v0.4.1"
+hooks= [
+    { id = "docstring-tailor", args = ["--style", "google"] },
+]
+```
+
+`prek util yaml-to-toml` converts an existing YAML config for you.
+
+### Local hook
+
+If your project already installs `docstring-tailor` (for example as a `uv` dev dependency), you can run it as a `repo: local` hook. pre-commit then never clones a remote repo, which is handy in locked-down or offline environments:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: docstring-tailor
+        name: docstring-tailor
+        entry: uv run docstring_tailor format --style google
+        language: system
+        types: [python]
+        pass_filenames: true
+```
+
+For CI, run `docstring-tailor format --diff` instead: it never writes files and exits non-zero when any docstring would change, so it can gate a pipeline.
+
 ## Example docstrings
 
 1. [Module docstring](#module-docstring)
@@ -408,6 +461,47 @@ def example_function(example_argument_1: str, example_argument_2: int) -> str:
 - In the `Examples` section, start the Python REPL with `>>>` and use `...` for continuation lines, matching Pydoc conventions — same as Google style.
 - These same section keywords can also be used in module or class docstrings — for example, a `Parameters` section in a class docstring, or an `Examples` section in a module docstring.
 
+**Sphinx / reST**
+
+```python
+def example_function(example_argument_1: str, example_argument_2: int) -> str:
+    """Demonstrates a Sphinx-style function docstring with multiple
+    sections.
+
+    This function exists purely as a formatting example and
+    illustrates how parameters, return values, and raised exceptions
+    are documented using reStructuredText info fields.
+
+    :param example_argument_1: First example input value used to
+        construct a formatted result string.
+    :type example_argument_1: str
+    :param example_argument_2: Second example input value used to
+        influence the transformation logic.
+    :type example_argument_2: int
+    :returns: A formatted string combining both input arguments into a
+        single human-readable representation.
+    :rtype: str
+    :raises ValueError: Raised when example_argument_2 is negative or
+        zero, as only positive integers are considered valid in this
+        demonstration.
+
+    .. note::
+        Additional informational directives such as ``.. note::`` and
+        ``.. warning::`` are recognized and preserved during
+        formatting.
+    """
+    if example_argument_2 <= 0:
+        raise ValueError("example_argument_2 must be positive")
+
+    return f"{example_argument_1}-{example_argument_2}"
+```
+
+- Parameters are documented with `:param name: description` info fields, and their types with a separate `:type name: type` field. An inline form (`:param str name: description`) is also accepted on input and is split into the two-field form on output.
+- Types are genuinely optional in reST: a `:param:` without a matching `:type:` is preserved as-is, and `docstring_tailor` never fabricates a type when one is absent.
+- Return values use `:returns:` (with `:return:` accepted as an alias), and the return type uses `:rtype:`.
+- Raised exceptions use `:raises Exception: description` (`:raise`, `:except` and `:exception` are accepted as aliases).
+- Informational directives such as `.. note::`, `.. warning::`, `.. seealso::` and `.. example::` are recognized and their indented bodies are formatted while the directive header is preserved.
+
 ### Codeblocks
 
 **Google / Numpy** (identical for this example)
@@ -589,6 +683,8 @@ You don't wrap text because wrapping is a skill issue. You let photons travel un
 | <div style="width:70px">Resource</div> | <div style="width:100px">Description</div> | <div style="width:130px">Link</div>
 |---|---|---|
 | PEP 257 - Docstring Conventions | Documents the semantics and conventions associated with Python docstrings. | [Link](https://peps.python.org/pep-0257/) |
+| PEP 287 - reStructuredText Docstring Format | Specifies a reStructuredText-based markup convention for Python docstrings, the basis of the Sphinx/reST style. | [Link](https://peps.python.org/pep-0287) |
+| PEP 484 - Type Hints | Provides a standard syntax for type annotations in Python. | [Link](https://peps.python.org/pep-0484/) |
 | Google Python Style Guide | Lists *dos and don'ts* for Python programs. | [Link](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings) |
 | Numpy Style Guide | Describes the syntax and best practices for docstrings used with the numpydoc extension for Sphinx | [Link](https://numpydoc.readthedocs.io/en/latest/format.html) |
 | Types of indentation | Wikipedia article that defines different kinds of indentation | [Link](https://en.wikipedia.org/wiki/Indentation_(typesetting)) |
@@ -610,6 +706,8 @@ You don't wrap text because wrapping is a skill issue. You let photons travel un
 | `0.2.1` | 2026-06-11 | Feature update | <ul><li>Added the `-V`/`--version` command to the CLI.</li><li>Added the `--exclude` command to the CLI.</li><li>Added the `--diff` command to the CLI.</li><li>Added the 'Demo' part to to the `README.md`.</ul> |
 | `0.3.0` | 2026-07-20 | Feature update & bug fixes | <ul><li>Introduced a style-agnostic intermediate representation (IR) model and refactored parsing into an abstract base class hierarchy. Google and NumPy docstrings now parse into the same IR via `IndentationBasedParser` subclasses, enabling lossless conversion between styles. Structured list parsing is delegated to style-specific implementations to handle syntactic differences (Google's inline `name (type):` vs. NumPy's `name : type` on separate lines).</li><li>Refactored rendering to match the parser architecture: `DocstringRendererBase` (ABC) with style-specific subclasses that implement two hooks — section header formatting (Google's `Args:` vs. NumPy's `Parameters` + underline) and section body indentation rules (confirmed against numpy's own docstrings to keep bodies flush with headers, unlike Google). Keyword translation between styles happens automatically during conversion.</li><li>Code sections and Python REPL blocks now also can be created outside the 'Example(s)' section.</li><li>Fixed a bug when codeblock sections contain blank lines.</li><li>Fixed a bug when the docstring starts immediately with an (un)ordered list.</li><li>Removed `detect-lists` as CLI parameter, because the logic should always be applied if the docstring contains (un)ordered lists.</li><li>Changed behaviour for empty docstrings so that it consistent with Ruff.</li></ul> |
 | `0.3.1` | 2026-07-21 | Small fixes | <ul><li>The `style` parameter does not have a default argument anymore, instead it always has to be configured explicitly by the user.</li><li>Fixed a bug where one-line docstrings inside indented scopes (e.g. class or method bodies) were wrapped to multiple lines prematurely, due to indentation being counted twice when checking against the configured line length.</li> <li>Added an exception, consistent with Ruff, allowing a one-line docstring to exceed the configured line length by up to 3 characters when only the closing triple quotes would otherwise be pushed onto their own line. This prevents docstring_tailor and Ruff from repeatedly reformatting the same docstring back and forth when both are run as pre-commit hooks.</li></ul> |
+| `0.4.0` | 2026-07-24 | Feature update | <ul><li>Added support for the Sphinx/reST docstring `style`, covering both parsing and rendering. Sphinx docstrings now parse into the same style-agnostic intermediate representation (IR) as Google and NumPy, enabling lossless conversion in all directions between the three styles (`format --style sphinx` and `convert` to/from `sphinx`).</li><li>Extracted a shared `DocstringParserBase` holding the style-agnostic flat-content pipeline; `IndentationBasedParser` (Google/NumPy) and the new directive-based `SphinxDocstringParser` both build on it, reusing the existing pipeline rather than duplicating logic.</li><li>The Sphinx parser handles info-field lists (`:param:`/`:type:`, `:returns:`/`:rtype:`, `:raises:`), the inline parameter form (`:param str name:`), field/type pairing by name, tag aliases (`:return:`, `:raise:`, `:except:`, `:exception:`), and informational directives (`.. note::`, `.. warning::`, `.. seealso::`, `.. example::`).</li><li>The Sphinx renderer emits a contiguous info-field list with separate `:type:`/`:rtype:` lines, with hanging-indent wrapping of field bodies.</li><li>Modelled an absent parameter type as `None` in the IR (never fabricated), and updated the Google and NumPy renderers to degrade gracefully when a type is undocumented.</li><li>Reorganized the golden-file test fixtures into per-style folders (`google/`, `sphinx/`, `convert/`), with the fixture style folder derived automatically from each test case's configuration.</li></ul> |
+| `0.4.1` | 2026-09-12 | Robustness & bug fixes | <ul><li> Made structured-list parsing resilient to malformed entries: a missing `:` separator or a missing `(type)` annotation no longer crashes. The entry's text is preserved (with name and type left unset) and rendered as written, so formatting never fails on imperfect docstrings.</li><li> Modelled a `Raises` entry that lacks a `:` as an unnamed error (`error_type` set to `None`) in the IR, consistent with how unclassifiable parameter entries are handled, and guarded the Google, Numpy and Sphinx renderes accordingly.</li><li> The CLI now processes each file independently: files that cannot be read, decoded, or parsed as Python are reported with a specific error message and skipped, so a single malformed file no longer aborts the whole run.</li><li> Added a Ruff-style run summary (e.g. `2 files reformatted, 1 file left unchanged`) and stopped rewriting files whose content did not change.</li><li>Aligned exit codes with Ruff: `format` exits non-zero only on errors (write mode) or when changes are needed (`--diff`), and `convert` exits non-zero only on errors, enabling reliable use in pre-commit and CI.</li><li>Removed a leftover debug `print` from the CLI output.</li><li> Published a `pre-commit-config.yaml` hook definition so `docstring-tailor` can run as a pre-commit / prek hook via `repo:`, with hosted, local, and `prek.toml` setups documented in the README </li></ul> |
 
 ## Roadmap
 
@@ -627,8 +725,16 @@ You don't wrap text because wrapping is a skill issue. You let photons travel un
 - Formatting module for the remaining docstring formats (Sphinx, Epydoc), driven
   entirely by the same IR already used for Google and NumPy.
 
+### Finish the Sphinx/reST implementation
+
+The core Sphinx style (parameters, returns, raises, and the common admonitions) is supported, but full coverage of every Sphinx construct is not there yet. Currently, unrecognized constructs are passed through as plain paragraph text — never dropped, but not parsed into a structured section, so they don't wrap as fields and don't convert to a Google/NumPy equivalent. The following would close that gap:
+
+- Class attribute fields (`:ivar:`, `:cvar:`, `:var:` paired with `:vartype:`), mapped onto the same `Attributes` section Google and NumPy already expose, so class docstrings round-trip and convert like the other styles. Requires a new field-pairing path in the parser, an `Attributes` render path in the renderer, and a fix to the keyword translation tables (which currently fold Attributes into Parameters).
+- Keyword-only argument fields (`:keyword:` / `:kwarg:` with `:kwtype:`), aliased onto the existing parameter/type handling.
+- The broader set of admonition directives (`.. tip::`, `.. important::`, `.. caution::`, `.. attention::`, `.. hint::`, `.. danger::`, `.. error::`, `.. todo::`, `.. deprecated::`, `.. versionadded::`, `.. versionchanged::`), added to the directive-to-header map so their bodies format as named paragraphs. Headers without a Google/NumPy equivalent pass through unchanged on conversion.
+- Literal-body directives (`.. code-block::`, `.. math::`) — more involved, because their content must be preserved verbatim and never reflowed, and there is no clean equivalent in the current IR. Needs a dedicated literal-block IR node before it can be handled safely.
+
 ### Nice to have
-- Make sure the package can be used as a pre-commit hook.
 - LSP (Language Server Protocol) support, enabling real-time feedback on malformed
   docstrings directly in editors like VS Code, PyCharm and Neovim. Built on top of
   the validation layer and the existing parser, with `pygls` handling the protocol.

{docstring_tailor-0.3.1 → docstring_tailor-0.4.1}/README.md

@@ -11,16 +11,17 @@ Formats Python docstrings to PEP 257 style with configurable line length.
 ## Table of Contents
 1. [Demo](#demo)
 2. [Installation](#Installation)
-3. [Quick start](#quick_start)
+3. [Quick start](#quick-start)
 4. [API Overview](#api-overview)
     - [Command](#command)
     - [Options](#options)
     - [Examples](#examples)
-5. [Example docstrings](#example-docstrings)
-6. [What Your Line Length Says About You!](#what-your-line-length-says-about-you)
-7. [Resources](#resources)
-8. [Release Notes](#release_notes)
-9. [Roadmap](#roadmap)
+5. [Pre-commit and prek hook](#pre-commit-and-prek-hook)
+6. [Example docstrings](#example-docstrings)
+7. [What Your Line Length Says About You!](#what-your-line-length-says-about-you)
+8. [Resources](#resources)
+9. [Release Notes](#release-notes)
+10. [Roadmap](#roadmap)
 
 ## Demo
 
@@ -83,7 +84,7 @@ line-length = 88
 line-length = 88
 ```
 
-Define a docstring style. Two styles are currently supported: [Google](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) and [NumPy](https://numpydoc.readthedocs.io/en/latest/format.html). Google is the default. Explicit configuration:
+Define a docstring style. Three styles are currently supported: [Google](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html), [NumPy](https://numpydoc.readthedocs.io/en/latest/format.html), and [Sphinx](https://www.sphinx-doc.org/en/master/usage/domains/python.html#info-field-lists). The style always has to be configured explicitly.
 
 ```bash
 uv run docstring_tailor format --style numpy
@@ -102,6 +103,8 @@ To convert existing docstrings from one style to another, use the `convert` comm
 uv run docstring_tailor convert my_file.py --from-style google --to-style numpy
 ```
 
+`docstring-tailor` can also run as a [pre-commit](https://pre-commit.com/) / [prek](https://github.com/j178/prek) hook so docstrings stay formatted on every commit, see [Pre-commit and prek hook](#pre-commit-and-prek-hook).
+
 ## API Overview
 
 ### Commands
@@ -132,20 +135,20 @@ If no paths are provided, `docstring_tailor` will attempt to locate and format f
 
 | <div style="width:140px">Option</div> | <div style="width:50px">Type</div> | <div style="width:80px">Default</div> | Description |
 |---|---|---|---|
-| `--line-length`      | `int`  | 100    | Maximum number of characters allowed per line after formatting. |
-| `--style`            | `str`  | google | Docstring style to format to. `google` or `numpy`. |
-| `--exclude`          | `str`  | —      | A glob pattern for paths to exclude. Can be passed multiple times. Single-path patterns (e.g. `tests`, `*.pyi`) match by name anywhere in the tree. Relative patterns (e.g. `src/generated/*.py`) match against the path relative to the project root. |
-| `--diff`             | flag   | —      | Print a unified diff of changes to stdout instead of modifying files. No files are written when this flag is set. |
+| `--line-length`      | `int`  | 100        | Maximum number of characters allowed per line after formatting. |
+| `--style`            | `str`  | *required* | Docstring style to format to. `google`, `numpy` or `sphinx`. |
+| `--exclude`          | `str`  | —          | A glob pattern for paths to exclude. Can be passed multiple times. Single-path patterns (e.g. `tests`, `*.pyi`) match by name anywhere in the tree. Relative patterns (e.g. `src/generated/*.py`) match against the path relative to the project root. |
+| `--diff`             | flag   | —          | Print a unified diff of changes to stdout instead of modifying files. No files are written when this flag is set. |
 
 #### `convert`
 
 | <div style="width:140px">Option</div> | <div style="width:50px">Type</div> | <div style="width:80px">Default</div> | Description |
 |---|---|---|---|
-| `--from-style`       | `str`  | *required* | Docstring style to convert from. `google` or `numpy`. |
-| `--to-style`         | `str`  | *required* | Docstring style to convert to. `google` or `numpy`. Must differ from `--from-style`. |
-| `--line-length`      | `int`  | 100    | Maximum number of characters allowed per line after formatting. |
-| `--exclude`          | `str`  | —      | A glob pattern for paths to exclude. Can be passed multiple times. Single-path patterns (e.g. `tests`, `*.pyi`) match by name anywhere in the tree. Relative patterns (e.g. `src/generated/*.py`) match against the path relative to the project root. |
-| `--diff`             | flag   | —      | Print a unified diff of changes to stdout instead of modifying files. No files are written when this flag is set. |
+| `--from-style`       | `str`  | *required* | Docstring style to convert from. `google`, `numpy` or `sphinx`. |
+| `--to-style`         | `str`  | *required* | Docstring style to convert to. `google`, `numpy` or `sphinx`. Must differ from `--from-style`. |
+| `--line-length`      | `int`  | 100        | Maximum number of characters allowed per line after formatting. |
+| `--exclude`          | `str`  | —          | A glob pattern for paths to exclude. Can be passed multiple times. Single-path patterns (e.g. `tests`, `*.pyi`) match by name anywhere in the tree. Relative patterns (e.g. `src/generated/*.py`) match against the path relative to the project root. |
+| `--diff`             | flag   | —          | Print a unified diff of changes to stdout instead of modifying files. No files are written when this flag is set. |
 
 `--from-style` and `--to-style` have no config-file or default fallback — both must be given explicitly on every `convert` invocation, and must be different from each other.
 
@@ -184,6 +187,56 @@ style = "google"
 exclude = ["tests", "src/generated/*.py"]
 ```
 
+## Pre-commit and prek hook
+
+`docstring-tailor` can run as a [pre-commit](https://pre-commit.com/) hook, and works unchanged with [prek](https://github.com/j178/prek), the drop-in reimplementation, so docstrings stay formatted automatically on every commit. When the hook reformats a file it rewrites it in place and stops the commit so you can review and re-stage the change, exactly like the Ruff or Black hooks.
+
+### Hosted hook
+
+Add the following to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/AukeB/docstring-tailor
+    rev: 0.4.1
+    hooks:
+      - id: docstring-tailor
+        args: ["--style", "google"]
+```
+
+- `--style` is required, use `google`, `numpy` or `sphinx`. Pass any other option (`--line-length`, `--exclude`) through `args`, or set them in a `[tool.docstring_tailor]` config block instead. `args` is a single flat list where every flag and every value is its own quoted element (e.g. `["--style", "google", "--line-length", "88"]`, with numbers quoted). Install the hook once with `pre-commit install` (or `prek install`).
+
+Prefer TOML? prek also reads a native `prek.toml`, a drop-in alternative to `.pre-commit-config.yaml` (upstream `pre-commit` ignores it). The same hook in `prek.toml`
+
+```toml
+[[repos]]
+repo = "https://github.com/AukeB/docstring-tailor"
+rev = "v0.4.1"
+hooks= [
+    { id = "docstring-tailor", args = ["--style", "google"] },
+]
+```
+
+`prek util yaml-to-toml` converts an existing YAML config for you.
+
+### Local hook
+
+If your project already installs `docstring-tailor` (for example as a `uv` dev dependency), you can run it as a `repo: local` hook. pre-commit then never clones a remote repo, which is handy in locked-down or offline environments:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: docstring-tailor
+        name: docstring-tailor
+        entry: uv run docstring_tailor format --style google
+        language: system
+        types: [python]
+        pass_filenames: true
+```
+
+For CI, run `docstring-tailor format --diff` instead: it never writes files and exits non-zero when any docstring would change, so it can gate a pipeline.
+
 ## Example docstrings
 
 1. [Module docstring](#module-docstring)
@@ -375,6 +428,47 @@ def example_function(example_argument_1: str, example_argument_2: int) -> str:
 - In the `Examples` section, start the Python REPL with `>>>` and use `...` for continuation lines, matching Pydoc conventions — same as Google style.
 - These same section keywords can also be used in module or class docstrings — for example, a `Parameters` section in a class docstring, or an `Examples` section in a module docstring.
 
+**Sphinx / reST**
+
+```python
+def example_function(example_argument_1: str, example_argument_2: int) -> str:
+    """Demonstrates a Sphinx-style function docstring with multiple
+    sections.
+
+    This function exists purely as a formatting example and
+    illustrates how parameters, return values, and raised exceptions
+    are documented using reStructuredText info fields.
+
+    :param example_argument_1: First example input value used to
+        construct a formatted result string.
+    :type example_argument_1: str
+    :param example_argument_2: Second example input value used to
+        influence the transformation logic.
+    :type example_argument_2: int
+    :returns: A formatted string combining both input arguments into a
+        single human-readable representation.
+    :rtype: str
+    :raises ValueError: Raised when example_argument_2 is negative or
+        zero, as only positive integers are considered valid in this
+        demonstration.
+
+    .. note::
+        Additional informational directives such as ``.. note::`` and
+        ``.. warning::`` are recognized and preserved during
+        formatting.
+    """
+    if example_argument_2 <= 0:
+        raise ValueError("example_argument_2 must be positive")
+
+    return f"{example_argument_1}-{example_argument_2}"
+```
+
+- Parameters are documented with `:param name: description` info fields, and their types with a separate `:type name: type` field. An inline form (`:param str name: description`) is also accepted on input and is split into the two-field form on output.
+- Types are genuinely optional in reST: a `:param:` without a matching `:type:` is preserved as-is, and `docstring_tailor` never fabricates a type when one is absent.
+- Return values use `:returns:` (with `:return:` accepted as an alias), and the return type uses `:rtype:`.
+- Raised exceptions use `:raises Exception: description` (`:raise`, `:except` and `:exception` are accepted as aliases).
+- Informational directives such as `.. note::`, `.. warning::`, `.. seealso::` and `.. example::` are recognized and their indented bodies are formatted while the directive header is preserved.
+
 ### Codeblocks
 
 **Google / Numpy** (identical for this example)
@@ -556,6 +650,8 @@ You don't wrap text because wrapping is a skill issue. You let photons travel un
 | <div style="width:70px">Resource</div> | <div style="width:100px">Description</div> | <div style="width:130px">Link</div>
 |---|---|---|
 | PEP 257 - Docstring Conventions | Documents the semantics and conventions associated with Python docstrings. | [Link](https://peps.python.org/pep-0257/) |
+| PEP 287 - reStructuredText Docstring Format | Specifies a reStructuredText-based markup convention for Python docstrings, the basis of the Sphinx/reST style. | [Link](https://peps.python.org/pep-0287) |
+| PEP 484 - Type Hints | Provides a standard syntax for type annotations in Python. | [Link](https://peps.python.org/pep-0484/) |
 | Google Python Style Guide | Lists *dos and don'ts* for Python programs. | [Link](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings) |
 | Numpy Style Guide | Describes the syntax and best practices for docstrings used with the numpydoc extension for Sphinx | [Link](https://numpydoc.readthedocs.io/en/latest/format.html) |
 | Types of indentation | Wikipedia article that defines different kinds of indentation | [Link](https://en.wikipedia.org/wiki/Indentation_(typesetting)) |
@@ -577,6 +673,8 @@ You don't wrap text because wrapping is a skill issue. You let photons travel un
 | `0.2.1` | 2026-06-11 | Feature update | <ul><li>Added the `-V`/`--version` command to the CLI.</li><li>Added the `--exclude` command to the CLI.</li><li>Added the `--diff` command to the CLI.</li><li>Added the 'Demo' part to to the `README.md`.</ul> |
 | `0.3.0` | 2026-07-20 | Feature update & bug fixes | <ul><li>Introduced a style-agnostic intermediate representation (IR) model and refactored parsing into an abstract base class hierarchy. Google and NumPy docstrings now parse into the same IR via `IndentationBasedParser` subclasses, enabling lossless conversion between styles. Structured list parsing is delegated to style-specific implementations to handle syntactic differences (Google's inline `name (type):` vs. NumPy's `name : type` on separate lines).</li><li>Refactored rendering to match the parser architecture: `DocstringRendererBase` (ABC) with style-specific subclasses that implement two hooks — section header formatting (Google's `Args:` vs. NumPy's `Parameters` + underline) and section body indentation rules (confirmed against numpy's own docstrings to keep bodies flush with headers, unlike Google). Keyword translation between styles happens automatically during conversion.</li><li>Code sections and Python REPL blocks now also can be created outside the 'Example(s)' section.</li><li>Fixed a bug when codeblock sections contain blank lines.</li><li>Fixed a bug when the docstring starts immediately with an (un)ordered list.</li><li>Removed `detect-lists` as CLI parameter, because the logic should always be applied if the docstring contains (un)ordered lists.</li><li>Changed behaviour for empty docstrings so that it consistent with Ruff.</li></ul> |
 | `0.3.1` | 2026-07-21 | Small fixes | <ul><li>The `style` parameter does not have a default argument anymore, instead it always has to be configured explicitly by the user.</li><li>Fixed a bug where one-line docstrings inside indented scopes (e.g. class or method bodies) were wrapped to multiple lines prematurely, due to indentation being counted twice when checking against the configured line length.</li> <li>Added an exception, consistent with Ruff, allowing a one-line docstring to exceed the configured line length by up to 3 characters when only the closing triple quotes would otherwise be pushed onto their own line. This prevents docstring_tailor and Ruff from repeatedly reformatting the same docstring back and forth when both are run as pre-commit hooks.</li></ul> |
+| `0.4.0` | 2026-07-24 | Feature update | <ul><li>Added support for the Sphinx/reST docstring `style`, covering both parsing and rendering. Sphinx docstrings now parse into the same style-agnostic intermediate representation (IR) as Google and NumPy, enabling lossless conversion in all directions between the three styles (`format --style sphinx` and `convert` to/from `sphinx`).</li><li>Extracted a shared `DocstringParserBase` holding the style-agnostic flat-content pipeline; `IndentationBasedParser` (Google/NumPy) and the new directive-based `SphinxDocstringParser` both build on it, reusing the existing pipeline rather than duplicating logic.</li><li>The Sphinx parser handles info-field lists (`:param:`/`:type:`, `:returns:`/`:rtype:`, `:raises:`), the inline parameter form (`:param str name:`), field/type pairing by name, tag aliases (`:return:`, `:raise:`, `:except:`, `:exception:`), and informational directives (`.. note::`, `.. warning::`, `.. seealso::`, `.. example::`).</li><li>The Sphinx renderer emits a contiguous info-field list with separate `:type:`/`:rtype:` lines, with hanging-indent wrapping of field bodies.</li><li>Modelled an absent parameter type as `None` in the IR (never fabricated), and updated the Google and NumPy renderers to degrade gracefully when a type is undocumented.</li><li>Reorganized the golden-file test fixtures into per-style folders (`google/`, `sphinx/`, `convert/`), with the fixture style folder derived automatically from each test case's configuration.</li></ul> |
+| `0.4.1` | 2026-09-12 | Robustness & bug fixes | <ul><li> Made structured-list parsing resilient to malformed entries: a missing `:` separator or a missing `(type)` annotation no longer crashes. The entry's text is preserved (with name and type left unset) and rendered as written, so formatting never fails on imperfect docstrings.</li><li> Modelled a `Raises` entry that lacks a `:` as an unnamed error (`error_type` set to `None`) in the IR, consistent with how unclassifiable parameter entries are handled, and guarded the Google, Numpy and Sphinx renderes accordingly.</li><li> The CLI now processes each file independently: files that cannot be read, decoded, or parsed as Python are reported with a specific error message and skipped, so a single malformed file no longer aborts the whole run.</li><li> Added a Ruff-style run summary (e.g. `2 files reformatted, 1 file left unchanged`) and stopped rewriting files whose content did not change.</li><li>Aligned exit codes with Ruff: `format` exits non-zero only on errors (write mode) or when changes are needed (`--diff`), and `convert` exits non-zero only on errors, enabling reliable use in pre-commit and CI.</li><li>Removed a leftover debug `print` from the CLI output.</li><li> Published a `pre-commit-config.yaml` hook definition so `docstring-tailor` can run as a pre-commit / prek hook via `repo:`, with hosted, local, and `prek.toml` setups documented in the README </li></ul> |
 
 ## Roadmap
 
@@ -594,8 +692,16 @@ You don't wrap text because wrapping is a skill issue. You let photons travel un
 - Formatting module for the remaining docstring formats (Sphinx, Epydoc), driven
   entirely by the same IR already used for Google and NumPy.
 
+### Finish the Sphinx/reST implementation
+
+The core Sphinx style (parameters, returns, raises, and the common admonitions) is supported, but full coverage of every Sphinx construct is not there yet. Currently, unrecognized constructs are passed through as plain paragraph text — never dropped, but not parsed into a structured section, so they don't wrap as fields and don't convert to a Google/NumPy equivalent. The following would close that gap:
+
+- Class attribute fields (`:ivar:`, `:cvar:`, `:var:` paired with `:vartype:`), mapped onto the same `Attributes` section Google and NumPy already expose, so class docstrings round-trip and convert like the other styles. Requires a new field-pairing path in the parser, an `Attributes` render path in the renderer, and a fix to the keyword translation tables (which currently fold Attributes into Parameters).
+- Keyword-only argument fields (`:keyword:` / `:kwarg:` with `:kwtype:`), aliased onto the existing parameter/type handling.
+- The broader set of admonition directives (`.. tip::`, `.. important::`, `.. caution::`, `.. attention::`, `.. hint::`, `.. danger::`, `.. error::`, `.. todo::`, `.. deprecated::`, `.. versionadded::`, `.. versionchanged::`), added to the directive-to-header map so their bodies format as named paragraphs. Headers without a Google/NumPy equivalent pass through unchanged on conversion.
+- Literal-body directives (`.. code-block::`, `.. math::`) — more involved, because their content must be preserved verbatim and never reflowed, and there is no clean equivalent in the current IR. Needs a dedicated literal-block IR node before it can be handled safely.
+
 ### Nice to have
-- Make sure the package can be used as a pre-commit hook.
 - LSP (Language Server Protocol) support, enabling real-time feedback on malformed
   docstrings directly in editors like VS Code, PyCharm and Neovim. Built on top of
   the validation layer and the existing parser, with `pygls` handling the protocol.

{docstring_tailor-0.3.1 → docstring_tailor-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring-tailor"
-version = "0.3.1"
+version = "0.4.1"
 description = "Formats Python docstrings to PEP 257 style with configurable line length."
 authors = [{ name = "Auke Bruinsma", email = "afbruinsma@gmail.com" }]
 license = { file = "LICENSE" }

{docstring_tailor-0.3.1 → docstring_tailor-0.4.1}/src/docstring_tailor/cli_config.py

@@ -16,7 +16,7 @@ class DocstringStyle(str, Enum):
     epydoc = "epydoc"
 
 
-SUPPORTED_STYLES = {DocstringStyle.google, DocstringStyle.numpy}
+SUPPORTED_STYLES = {DocstringStyle.google, DocstringStyle.numpy, DocstringStyle.sphinx}
 
 # Argument: '--line-length'
 LINE_LENGTH_MIN: int = 30

{docstring_tailor-0.3.1 → docstring_tailor-0.4.1}/src/docstring_tailor/constants.py

@@ -21,6 +21,7 @@ RE_PATTERN_STRUCTURED_LIST_NAME_AND_TYPE = re.compile(
 )
 RE_PATTERN_NUMPY_SECTION_UNDERLINE = re.compile(r"^-+$")
 
+
 # =========================================
 # Constants used for all docstring formats.
 # =========================================
@@ -53,23 +54,13 @@ UNORDERED_LIST_MARKER: str = "- "
 ORDERED_LIST_SEPARATOR = ". "
 
 
-# ====================================================
-# Constants used for multiple docstings (but not all).
-# ====================================================
-
-
-# Related to StructuredList sections (Use in Google and Numpy format)
-STRUCTURED_LIST_DESCRIPTION_SEPARATOR: str = ":"
-PARAMETER_TYPE_ANNOTATION_OPEN: str = "("
-PARAMETER_TYPE_ANNOTATION_CLOSE: str = ")"
-
-
 # ============================================
 # Constants used for single docstring formats.
 # ============================================
 
 
-# Google
+# === Google ===
+
 GOOGLE_NAMED_PARAGRAPH_SECTIONS = frozenset(
     {
         "Note",
@@ -91,14 +82,17 @@ GOOGLE_ALL_SECTION_KEYWORDS = (
     GOOGLE_NAMED_PARAGRAPH_SECTIONS | GOOGLE_STRUCTURED_LIST_SECTIONS
 )
 
+GOOGLE_STRUCTURED_LIST_DESCRIPTION_SEPARATOR: str = ":"
+
+# === NumPy ---
 
-# NumPy
 NUMPY_ITEM_SECTIONS = frozenset(
     {"Attributes", "Methods", "Parameters", "Raises", "Receives", "Returns", "Yields"}
 )
 NUMPY_PLAIN_SECTIONS = frozenset({"Examples", "Notes", "References", "See Also"})
 NUMPY_SECTION_HEADERS = NUMPY_ITEM_SECTIONS | NUMPY_PLAIN_SECTIONS
 
+NUMPY_STRUCTURED_LIST_NAME_TYPE_SEPARATOR: str = ":"
 
 # Sphinx/reST-style
 SPHINX_ITEM_DIRECTIVES = frozenset({":param", ":raises", ":returns", ":rtype", ":type"})
@@ -107,8 +101,58 @@ SPHINX_PLAIN_DIRECTIVES = frozenset(
 )
 SPHINX_DIRECTIVES = SPHINX_ITEM_DIRECTIVES | SPHINX_PLAIN_DIRECTIVES
 
+# === Sphinx ===
+
+# Sphinx field tags, grouped by the IR section they map to. Aliases (singular
+# and plural spellings) are accepted on input; the renderer emits one canonical
+# spelling per group. ':param' also accepts an inline type ':param <type>
+# <name>:', handled by the parser.
+SPHINX_PARAM_TAGS = frozenset({":param", ":parameter", ":arg", ":argument"})
+SPHINX_TYPE_TAGS = frozenset({":type"})
+SPHINX_RETURN_TAGS = frozenset({":return", ":returns"})
+SPHINX_RTYPE_TAGS = frozenset({":rtype"})
+SPHINX_RAISE_TAGS = frozenset({":raise", ":raises", ":except", ":exception"})
+
+# All field tags that open a structured-list entry (as opposed to type metadata
+# for a preceding entry). Used to detect the start of a field-list block.
+SPHINX_FIELD_TAGS = (
+    SPHINX_PARAM_TAGS
+    | SPHINX_TYPE_TAGS
+    | SPHINX_RETURN_TAGS
+    | SPHINX_RTYPE_TAGS
+    | SPHINX_RAISE_TAGS
+)
+
+# Canonical section keywords used for Sphinx StructuredList nodes in the IR, so
+# keyword translation and rendering share one vocabulary.
+SPHINX_KEYWORD_PARAMETERS: str = "Parameters"
+SPHINX_KEYWORD_RETURNS: str = "Returns"
+SPHINX_KEYWORD_RAISES: str = "Raises"
+
+# Canonical Sphinx directive-to-header mapping for admonition sections rendered
+# as NamedParagraph nodes.
+SPHINX_DIRECTIVE_HEADERS: dict[str, str] = {
+    ".. note::": "Note",
+    ".. warning::": "Warning",
+    ".. seealso::": "See Also",
+    ".. example::": "Example",
+}
+
+# Reverse mapping: canonical header to its Sphinx directive marker, for
+# rendering NamedParagraph nodes back to reST directives.
+SPHINX_HEADER_DIRECTIVES: dict[str, str] = {
+    header: directive for directive, header in SPHINX_DIRECTIVE_HEADERS.items()
+}
+
+# Canonical Sphinx field-tag spellings emitted my the renderer.
+SPHINX_RENDER_PARAM_TAG: str = ":param"
+SPHINX_RENDER_TYPE_TAG: str = ":type"
+SPHINX_RENDER_RETURNS_TAG: str = ":returns"
+SPHINX_RENDER_RTYPE_TAG: str = ":rtype"
+SPHINX_RENDER_RAISES_TAG: str = ":raises"
+
+# === Epydoc ===
 
-# Epydoc-style docstring tag markers.
 EPYDOC_ITEM_TAGS = frozenset({"@param", "@raise", "@return", "@rtype", "@type"})
 EPYDOC_PLAIN_TAGS = frozenset({"@note", "@warning"})
 EPYDOC_TAGS = EPYDOC_ITEM_TAGS | EPYDOC_PLAIN_TAGS

{docstring_tailor-0.3.1 → docstring_tailor-0.4.1}/src/docstring_tailor/ir_model.py

@@ -62,12 +62,17 @@ class StructuredListParameter:
         name (str | None): The variable or attribute name, or None when the
             entry has no name -- the conventional shape for Returns and Yields
             entries, which document only the type.
-        type (str): The annotated type of the variable.
+        type (str | None): The annotated type of the variable, or None when no
+            type was documented. Types are optional in some styles (e.g.
+            Sphinx/reST field lists relying on PEP 484 signature hints), so
+            absence is modelled explicitly rather than as an empty string,
+            mirroring the name field. Renderers omit the type entirely when it
+            is None.
         description (str): The description of the variable.
     """
 
     name: str | None
-    type: str
+    type: str | None
     description: str
 
 
@@ -77,11 +82,14 @@ class StructuredListError:
     section.
 
     Attributes:
-        error_type (str): The exception type being raised.
+        error_type (str | None): The exception type being raised, or None when
+            the entry had no ':' separator and could not be split. The whole
+            entry is preserved in description instead, mirroring how an
+            unclassifiable parameter entry is handled.
         description (str): The description of when the error is raised.
     """
 
-    error_type: str
+    error_type: str | None
     description: str