docstring-tailor 0.3.0__tar.gz → 0.4.0__tar.gz

{docstring_tailor-0.3.0 → docstring_tailor-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring-tailor
-Version: 0.3.0
+Version: 0.4.0
 Summary: Formats Python docstrings to PEP 257 style with configurable line length.
 Author-email: Auke Bruinsma <afbruinsma@gmail.com>
 License: MIT License
@@ -116,7 +116,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
@@ -165,20 +165,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.
 
@@ -408,6 +408,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,7 +597,11 @@ Steps:
 
 ### 60 characters per line — The Minimalist Monk 🧘
 
-You believe every character has a purpose and every extra column is a personal failure 😤. You keep your docstrings short, your functions tiny, and your emotional attachment to whitespace surprisingly strong. You don't need room to explain your code because your code should be obvious. If a sentence doesn't fit in 60 characters, you simply rewrite the sentence until it does. Brevity is not a preference for you. Brevity is a lifestyle.
+You believe every character has a purpose and every extra column is a personal failure 😤. You keep your docstrings short, your functions tiny, and your emotional attachment to whitespace surprisingly strong. Variable names? Anything longer than two characters is wasteful bloat — x, y, z, and i are sufficient for any problem. Docstrings are memory theft; everything the code needs to say should be obvious from context or inferred through pure spiritual understanding 🙏. Why document when you could just make the code so minimalist that it transcends the need for explanation? Your motto: if it takes more than 60 characters to explain, the explanation itself is the bug, not the code.
+
+### 79 characters per line — The Precision Tuner ⚙️
+
+You didn't choose 79 characters; you derived it through first principles and a spreadsheet. You read every formatter's GitHub issues, every style guide's rationale, and you have strong opinions about why 80 is overrated but 78 is cowardice 😤. You've A/B tested readability on three different monitors, measured your own eye-tracking data, and lost sleep over whether \n counts toward the limit or not. You configure your linter to lint your linter, and you have a .editorconfig file that is longer than most people's actual code 📋. You know exactly why PEP 8 suggested 79 and you've defended this choice at dinner parties with the fervor of someone protecting their firstborn child 🛡️. You don't just use docstring_tailor; you've benchmarked it against seven alternatives and created a spreadsheet ranking their consistency. Your line length is not a preference—it's a thesis 📊. You sleep well knowing that you have optimized, and the universe is in perfect order, exactly 79 characters wide.
 
 ### 80 characters per line — The Digital Archaeologist 🦖
 
@@ -585,6 +630,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)) |
@@ -605,6 +652,8 @@ You don't wrap text because wrapping is a skill issue. You let photons travel un
 | `0.2.0` | 2026-06-07 | Feature update | <ul><li>Implemented the `detect-lists` parameter, adding support for unordered and ordered (numbered) lists in docstrings. When enabled, list structures are detected automatically and each list item is formatted onto its own line.</li><li>Introduced a declarative golden-file test framework for formatter validation. Test cases are now generated from parametrized templates using Cartesian-product expansion, significantly reducing boilerplate and improving scalability for configuration coverage.</li><li>Expanded this `README.md` with the 'API Overview', 'Release Notes', 'Example docstrings' and 'Roadmap' sections.</li><li>Test coverage: 75%</li></ul> |
 | `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> |
 
 ## Roadmap
 
@@ -622,6 +671,15 @@ 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

{docstring_tailor-0.3.0 → docstring_tailor-0.4.0}/README.md

@@ -83,7 +83,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
@@ -132,20 +132,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.
 
@@ -375,6 +375,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)
@@ -523,7 +564,11 @@ Steps:
 
 ### 60 characters per line — The Minimalist Monk 🧘
 
-You believe every character has a purpose and every extra column is a personal failure 😤. You keep your docstrings short, your functions tiny, and your emotional attachment to whitespace surprisingly strong. You don't need room to explain your code because your code should be obvious. If a sentence doesn't fit in 60 characters, you simply rewrite the sentence until it does. Brevity is not a preference for you. Brevity is a lifestyle.
+You believe every character has a purpose and every extra column is a personal failure 😤. You keep your docstrings short, your functions tiny, and your emotional attachment to whitespace surprisingly strong. Variable names? Anything longer than two characters is wasteful bloat — x, y, z, and i are sufficient for any problem. Docstrings are memory theft; everything the code needs to say should be obvious from context or inferred through pure spiritual understanding 🙏. Why document when you could just make the code so minimalist that it transcends the need for explanation? Your motto: if it takes more than 60 characters to explain, the explanation itself is the bug, not the code.
+
+### 79 characters per line — The Precision Tuner ⚙️
+
+You didn't choose 79 characters; you derived it through first principles and a spreadsheet. You read every formatter's GitHub issues, every style guide's rationale, and you have strong opinions about why 80 is overrated but 78 is cowardice 😤. You've A/B tested readability on three different monitors, measured your own eye-tracking data, and lost sleep over whether \n counts toward the limit or not. You configure your linter to lint your linter, and you have a .editorconfig file that is longer than most people's actual code 📋. You know exactly why PEP 8 suggested 79 and you've defended this choice at dinner parties with the fervor of someone protecting their firstborn child 🛡️. You don't just use docstring_tailor; you've benchmarked it against seven alternatives and created a spreadsheet ranking their consistency. Your line length is not a preference—it's a thesis 📊. You sleep well knowing that you have optimized, and the universe is in perfect order, exactly 79 characters wide.
 
 ### 80 characters per line — The Digital Archaeologist 🦖
 
@@ -552,6 +597,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)) |
@@ -572,6 +619,8 @@ You don't wrap text because wrapping is a skill issue. You let photons travel un
 | `0.2.0` | 2026-06-07 | Feature update | <ul><li>Implemented the `detect-lists` parameter, adding support for unordered and ordered (numbered) lists in docstrings. When enabled, list structures are detected automatically and each list item is formatted onto its own line.</li><li>Introduced a declarative golden-file test framework for formatter validation. Test cases are now generated from parametrized templates using Cartesian-product expansion, significantly reducing boilerplate and improving scalability for configuration coverage.</li><li>Expanded this `README.md` with the 'API Overview', 'Release Notes', 'Example docstrings' and 'Roadmap' sections.</li><li>Test coverage: 75%</li></ul> |
 | `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> |
 
 ## Roadmap
 
@@ -589,6 +638,15 @@ 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

{docstring_tailor-0.3.0 → docstring_tailor-0.4.0}/makefile

@@ -45,7 +45,7 @@ git:
 
 # Run full workflow: format, type-check, test, clean, commit
 all:
-	uv run src/docstring_tailor/main.py format --line-length 80
+	uv run src/docstring_tailor/main.py format --style google --line-length 80
 	make ruff
 	make ty
 	make pytest

{docstring_tailor-0.3.0 → docstring_tailor-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring-tailor"
-version = "0.3.0"
+version = "0.4.0"
 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.0 → docstring_tailor-0.4.0}/src/docstring_tailor/cli_config.py

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

{docstring_tailor-0.3.0 → docstring_tailor-0.4.0}/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.
 # =========================================
@@ -69,7 +70,8 @@ PARAMETER_TYPE_ANNOTATION_CLOSE: str = ")"
 # ============================================
 
 
-# Google
+# === Google ===
+
 GOOGLE_NAMED_PARAGRAPH_SECTIONS = frozenset(
     {
         "Note",
@@ -91,8 +93,8 @@ GOOGLE_ALL_SECTION_KEYWORDS = (
     GOOGLE_NAMED_PARAGRAPH_SECTIONS | GOOGLE_STRUCTURED_LIST_SECTIONS
 )
 
+# === NumPy ---
 
-# NumPy
 NUMPY_ITEM_SECTIONS = frozenset(
     {"Attributes", "Methods", "Parameters", "Raises", "Receives", "Returns", "Yields"}
 )
@@ -107,8 +109,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({":parma", ":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.0 → docstring_tailor-0.4.0}/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
 
 

{docstring_tailor-0.3.0 → docstring_tailor-0.4.0}/src/docstring_tailor/main.py

@@ -16,7 +16,6 @@ import typer
 
 from docstring_tailor.cli_config import (
     DEFAULT_PATHS,
-    DEFAULT_STYLE,
     LINE_LENGTH_DEFAULT,
     LINE_LENGTH_MAX,
     LINE_LENGTH_MIN,
@@ -198,9 +197,18 @@ def format_command(
     resolved_paths, resolved_line_length, resolved_exclude, file_config = (
         _resolve_common_options(paths=paths, line_length=line_length, exclude=exclude)
     )
-    resolved_style = style or DocstringStyle(
-        file_config.get("style", DEFAULT_STYLE.value)
-    )
+
+    resolved_style = style or file_config.get("style")
+
+    if resolved_style is None:
+        typer.echo(
+            "Error: Docstring style not specified. "
+            "Pass --style on the command line or set 'style' in your config file "
+            "(pyproject.toml or docstring_tailor.toml)."
+        )
+        raise typer.Exit(code=1)
+
+    resolved_style = DocstringStyle(resolved_style)
 
     _validate_supported_style(resolved_style)