format-docstring 0.1.4__tar.gz → 0.1.6__tar.gz

{format_docstring-0.1.4 → format_docstring-0.1.6}/CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.6] - 2025-10-13
+
+- Added
+  - New `--fix-rst-backticks` option to automatically convert single backticks
+    to double backticks per rST syntax
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.1.5...0.1.6
+
+## [0.1.5] - 2025-10-13
+
+- Added
+  - Support for `... ` (continuation of REPL lines) in the Examples section
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.1.4...0.1.5
+
 ## [0.1.4] - 2025-10-12
 
 - Added

{format_docstring-0.1.4 → format_docstring-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.1.4
+Version: 0.1.6
 Summary: A Python formatter to wrap/adjust docstring lines
 Author-email: jsh9 <25124332+jsh9@users.noreply.github.com>
 Maintainer-email: jsh9 <25124332+jsh9@users.noreply.github.com>
@@ -45,6 +45,7 @@ A Python formatter to automatically format numpy-style docstrings.
   - [2.2. One-line summaries are formatted to fit line length limit](#22-one-line-summaries-are-formatted-to-fit-line-length-limit)
   - [2.3. Minor typos can be automatically fixed](#23-minor-typos-can-be-automatically-fixed)
   - [2.4. Default value declarations are standardized](#24-default-value-declarations-are-standardized)
+  - [2.5. Single backticks are converted to double backticks (rST syntax)](#25-single-backticks-are-converted-to-double-backticks-rst-syntax)
 - [3. Installation](#3-installation)
 - [4. Usage](#4-usage)
   - [4.1. Command Line Interface](#41-command-line-interface)
@@ -209,6 +210,29 @@ def example_function(arg1, arg2, arg3, arg4):
     pass
 ```
 
+### 2.5. Single backticks are converted to double backticks (rST syntax)
+
+```diff
+def process_data(data):
+    """
+-    Process data using the `transform` function.
++    Process data using the ``transform`` function.
+
+    Parameters
+    ----------
+    data : dict
+-        Input data with keys `id`, `value`, and `timestamp`.
++        Input data with keys ``id``, ``value``, and ``timestamp``.
+
+    Returns
+    -------
+    dict
+-        Processed data with key `result`.
++        Processed data with key ``result``.
+    """
+    pass
+```
+
 ## 3. Installation
 
 ```bash
@@ -265,6 +289,8 @@ pre-commit install
   (default: 79)
 - `--docstring-style CHOICE`: Docstring style to target (`numpy` or `google`,
   default: `numpy`). Note: Currently only `numpy` style is fully supported.
+- `--fix-rst-backticks BOOL`: Automatically fix single backticks to double
+  backticks per rST syntax (default: True)
 - `--exclude TEXT`: Regex pattern to exclude files/directories (default:
   `\.git|\.tox|\.pytest_cache`)
 - `--config PATH`: Path to a `pyproject.toml` config file. If not specified,
@@ -290,6 +316,9 @@ format-docstring --config path/to/pyproject.toml src/
 
 # CLI options override config file settings
 format-docstring --config pyproject.toml --line-length 100 src/
+
+# Disable backtick fixing
+format-docstring --fix-rst-backticks=False my_module.py
 ```
 
 ### 5.3. `pyproject.toml` Configuration
@@ -301,6 +330,7 @@ override these settings:
 [tool.format_docstring]
 line_length = 79
 docstring_style = "numpy"
+fix_rst_backticks = true
 exclude = "\\.git|\\.venv|__pycache__"
 ```
 
@@ -310,6 +340,8 @@ exclude = "\\.git|\\.venv|__pycache__"
   79\)
 - `docstring_style` (str): Docstring style, either `"numpy"` or `"google"`
   (default: `"numpy"`)
+- `fix_rst_backticks` (bool): Automatically fix single backticks to double
+  backticks per rST syntax (default: `true`)
 - `exclude` (str): Regex pattern to exclude files/directories (default:
   `"\\.git|\\.tox|\\.pytest_cache"`)
 

{format_docstring-0.1.4 → format_docstring-0.1.6}/README.md

@@ -12,6 +12,7 @@ A Python formatter to automatically format numpy-style docstrings.
   - [2.2. One-line summaries are formatted to fit line length limit](#22-one-line-summaries-are-formatted-to-fit-line-length-limit)
   - [2.3. Minor typos can be automatically fixed](#23-minor-typos-can-be-automatically-fixed)
   - [2.4. Default value declarations are standardized](#24-default-value-declarations-are-standardized)
+  - [2.5. Single backticks are converted to double backticks (rST syntax)](#25-single-backticks-are-converted-to-double-backticks-rst-syntax)
 - [3. Installation](#3-installation)
 - [4. Usage](#4-usage)
   - [4.1. Command Line Interface](#41-command-line-interface)
@@ -176,6 +177,29 @@ def example_function(arg1, arg2, arg3, arg4):
     pass
 ```
 
+### 2.5. Single backticks are converted to double backticks (rST syntax)
+
+```diff
+def process_data(data):
+    """
+-    Process data using the `transform` function.
++    Process data using the ``transform`` function.
+
+    Parameters
+    ----------
+    data : dict
+-        Input data with keys `id`, `value`, and `timestamp`.
++        Input data with keys ``id``, ``value``, and ``timestamp``.
+
+    Returns
+    -------
+    dict
+-        Processed data with key `result`.
++        Processed data with key ``result``.
+    """
+    pass
+```
+
 ## 3. Installation
 
 ```bash
@@ -232,6 +256,8 @@ pre-commit install
   (default: 79)
 - `--docstring-style CHOICE`: Docstring style to target (`numpy` or `google`,
   default: `numpy`). Note: Currently only `numpy` style is fully supported.
+- `--fix-rst-backticks BOOL`: Automatically fix single backticks to double
+  backticks per rST syntax (default: True)
 - `--exclude TEXT`: Regex pattern to exclude files/directories (default:
   `\.git|\.tox|\.pytest_cache`)
 - `--config PATH`: Path to a `pyproject.toml` config file. If not specified,
@@ -257,6 +283,9 @@ format-docstring --config path/to/pyproject.toml src/
 
 # CLI options override config file settings
 format-docstring --config pyproject.toml --line-length 100 src/
+
+# Disable backtick fixing
+format-docstring --fix-rst-backticks=False my_module.py
 ```
 
 ### 5.3. `pyproject.toml` Configuration
@@ -268,6 +297,7 @@ override these settings:
 [tool.format_docstring]
 line_length = 79
 docstring_style = "numpy"
+fix_rst_backticks = true
 exclude = "\\.git|\\.venv|__pycache__"
 ```
 
@@ -277,6 +307,8 @@ exclude = "\\.git|\\.venv|__pycache__"
   79\)
 - `docstring_style` (str): Docstring style, either `"numpy"` or `"google"`
   (default: `"numpy"`)
+- `fix_rst_backticks` (bool): Automatically fix single backticks to double
+  backticks per rST syntax (default: `true`)
 - `exclude` (str): Regex pattern to exclude files/directories (default:
   `"\\.git|\\.tox|\\.pytest_cache"`)
 

{format_docstring-0.1.4 → format_docstring-0.1.6}/format_docstring/docstring_rewriter.py

@@ -18,6 +18,7 @@ def fix_src(
         *,
         line_length: int = 79,
         docstring_style: str = 'numpy',
+        fix_rst_backticks: bool = True,
 ) -> str:
     """Return code with only docstrings updated to wrapped content.
 
@@ -27,9 +28,11 @@ def fix_src(
         The full Python source code to process.
     line_length : int, default=79
         Target maximum line length for wrapping logic.
-
     docstring_style : str, default='numpy'
         The docstring style to target ('numpy' or 'google').
+    fix_rst_backticks : bool, default=True
+        If True, automatically fix single backticks to double backticks per
+        rST syntax.
 
     Returns
     -------
@@ -51,7 +54,12 @@ def fix_src(
 
     # Module-level docstring
     rep = build_replacement_docstring(
-        tree, source_code, line_starts, line_length, docstring_style
+        tree,
+        source_code,
+        line_starts,
+        line_length,
+        docstring_style,
+        fix_rst_backticks,
     )
     if rep is not None:
         replacements.append(rep)
@@ -62,7 +70,12 @@ def fix_src(
             node, ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef
         ):
             rep = build_replacement_docstring(
-                node, source_code, line_starts, line_length, docstring_style
+                node,
+                source_code,
+                line_starts,
+                line_length,
+                docstring_style,
+                fix_rst_backticks,
             )
             if rep is not None:
                 replacements.append(rep)
@@ -107,6 +120,7 @@ def build_replacement_docstring(
         line_starts: list[int],
         line_length: int,
         docstring_style: str = 'numpy',
+        fix_rst_backticks: bool = True,
 ) -> tuple[int, int, str] | None:
     """Compute a single docstring replacement for the given node.
 
@@ -120,9 +134,11 @@ def build_replacement_docstring(
         Line start offsets from :func:`_line_starts`.
     line_length : int
         Target maximum line length for wrapping logic.
-
     docstring_style : str, default='numpy'
         The docstring style to target ('numpy' or 'google').
+    fix_rst_backticks : bool, default=True
+        If True, automatically fix single backticks to double backticks per
+        rST syntax.
 
     Returns
     -------
@@ -164,6 +180,7 @@ def build_replacement_docstring(
         line_length=line_length,
         docstring_style=docstring_style,
         leading_indent=leading_indent_,  # type: ignore[arg-type]
+        fix_rst_backticks=fix_rst_backticks,
     )
 
     new_literal: str | None = rebuild_literal(original_literal, wrapped)
@@ -277,6 +294,7 @@ def wrap_docstring(
         line_length: int = 79,
         docstring_style: str = 'numpy',
         leading_indent: int = 0,
+        fix_rst_backticks: bool = True,
 ) -> str:
     """Wrap a docstring to the given line length (stub).
 
@@ -290,6 +308,9 @@ def wrap_docstring(
         The docstring style to target ('numpy' or 'google').
     leading_indent : int, default=0
         The number of indentation spaces of this docstring.
+    fix_rst_backticks : bool, default=True
+        If True, automatically fix single backticks to double backticks per
+        rST syntax.
 
     Returns
     -------
@@ -306,9 +327,15 @@ def wrap_docstring(
     style = (docstring_style or '').strip().lower()
     if style == 'google':
         return wrap_docstring_google(
-            docstring, line_length, leading_indent=leading_indent
+            docstring,
+            line_length,
+            leading_indent=leading_indent,
+            fix_rst_backticks=fix_rst_backticks,
         )
     # Default to NumPy-style for unknown/unspecified styles to be permissive.
     return wrap_docstring_numpy(
-        docstring, line_length, leading_indent=leading_indent
+        docstring,
+        line_length,
+        leading_indent=leading_indent,
+        fix_rst_backticks=fix_rst_backticks,
     )

{format_docstring-0.1.4 → format_docstring-0.1.6}/format_docstring/line_wrap_google.py

@@ -2,6 +2,7 @@ def wrap_docstring_google(
         docstring: str,
         line_length: int,
         leading_indent: int | None = None,
+        fix_rst_backticks: bool = True,
 ) -> str:
     """A placeholder for now."""  # noqa: D401
     return ''

{format_docstring-0.1.4 → format_docstring-0.1.6}/format_docstring/line_wrap_numpy.py

@@ -15,6 +15,7 @@ def wrap_docstring_numpy(
         docstring: str,
         line_length: int,
         leading_indent: int | None = None,
+        fix_rst_backticks: bool = False,
 ) -> str:
     """Wrap NumPy-style docstrings with light parsing rules.
 
@@ -103,8 +104,10 @@ def wrap_docstring_numpy(
             i += 1
             continue
 
-        # In Examples, skip wrapping for REPL lines
-        if in_examples and stripped.startswith('>>> '):
+        # In Examples, skip wrapping and backtick fixing for REPL lines
+        if in_examples and (
+            stripped.startswith('>>> ') or stripped.startswith('... ')
+        ):
             temp_out.append(line)
             i += 1
             continue
@@ -129,7 +132,10 @@ def wrap_docstring_numpy(
                 continue
 
             # Description lines (typically indented): wrap if too long
-            collect_to_temp_output(temp_out, line)
+            line_to_process = (
+                _fix_rst_backticks(line) if fix_rst_backticks else line
+            )
+            collect_to_temp_output(temp_out, line_to_process)
             i += 1
             continue
 
@@ -146,12 +152,18 @@ def wrap_docstring_numpy(
                 i += 1
                 continue
 
-            collect_to_temp_output(temp_out, line)
+            line_to_process = (
+                _fix_rst_backticks(line) if fix_rst_backticks else line
+            )
+            collect_to_temp_output(temp_out, line_to_process)
             i += 1
             continue
 
         # Examples or any other section
-        collect_to_temp_output(temp_out, line)
+        line_to_process = (
+            _fix_rst_backticks(line) if fix_rst_backticks else line
+        )
+        collect_to_temp_output(temp_out, line_to_process)
         i += 1
 
     out: list[str] = process_temp_output(temp_out, width=line_length)
@@ -401,3 +413,43 @@ def handle_single_line_docstring(
         return f'{prefix}\n{wrapped}\n{indent}{postfix}'
 
     return whole_docstring_literal
+
+
+def _fix_rst_backticks(docstring: str) -> str:
+    """
+    Fix single backticks to double backticks per rST syntax.
+
+    This function converts pairs of single backticks (`) to pairs of double
+    backticks (``). It handles various edge cases:
+    - Preserves existing double backticks
+    - Handles nested backticks
+    - Preserves code blocks and literal blocks
+
+    Parameters
+    ----------
+    docstring : str
+        The docstring content to process.
+
+    Returns
+    -------
+    str
+        The docstring with single backticks converted to double backticks.
+
+    Examples
+    --------
+    >>> _fix_rst_backticks('Use `foo` to do something')
+    'Use ``foo`` to do something'
+    >>> _fix_rst_backticks('Already has ``foo`` double backticks')
+    'Already has ``foo`` double backticks'
+    """
+    # Pattern to match single backticks that are not already part of double
+    # backticks. We look for:
+    # - A backtick not preceded by a backtick: (?<!`)
+    # - Followed by one or more non-backtick characters: ([^`]+)
+    # - Followed by a backtick not followed by another backtick: `(?!`)
+    #
+    # This pattern avoids matching backticks that are already part of ``...``
+    pattern = r'(?<!`)`([^`]+)`(?!`)'
+
+    # Replace single backtick pairs with double backtick pairs
+    return re.sub(pattern, r'``\1``', docstring)

{format_docstring-0.1.4 → format_docstring-0.1.6}/format_docstring/main_jupyter.py

@@ -54,18 +54,28 @@ from format_docstring.config import inject_config_from_file
     show_default=True,
     help='Docstring style to target',
 )
+@click.option(
+    '--fix-rst-backticks',
+    default=True,
+    show_default=True,
+    help='Fix single backticks to double backticks per rST syntax',
+)
 def main(
         paths: tuple[str, ...],
         config: str | None,  # noqa: ARG001 (used by Click callback)
         exclude: str,
         line_length: int,
         docstring_style: str,
+        fix_rst_backticks: bool,
 ) -> None:
     """Format .ipynb files."""
     ret = 0
     for path in paths:
         fixer = JupyterNotebookFixer(
-            path=path, exclude_pattern=exclude, line_length=line_length
+            path=path,
+            exclude_pattern=exclude,
+            line_length=line_length,
+            fix_rst_backticks=fix_rst_backticks,
         )
         fixer.docstring_style = docstring_style
         ret |= fixer.fix_one_directory_or_one_file()
@@ -82,9 +92,11 @@ class JupyterNotebookFixer(BaseFixer):
             path: str,
             exclude_pattern: str = r'\.git|\.tox|\.pytest_cache',
             line_length: int = 79,
+            fix_rst_backticks: bool = True,
     ) -> None:
         super().__init__(path=path, exclude_pattern=exclude_pattern)
         self.line_length = line_length
+        self.fix_rst_backticks = fix_rst_backticks
         self.docstring_style: str = 'numpy'
 
     def fix_one_directory_or_one_file(self) -> int:
@@ -140,6 +152,7 @@ class JupyterNotebookFixer(BaseFixer):
                     source_code=source_without_magic,
                     line_length=self.line_length,
                     docstring_style=self.docstring_style,
+                    fix_rst_backticks=self.fix_rst_backticks,
                 )
 
                 if fixed != source_without_magic:

{format_docstring-0.1.4 → format_docstring-0.1.6}/format_docstring/main_py.py

@@ -46,12 +46,19 @@ from format_docstring.config import inject_config_from_file
     show_default=True,
     help='Docstring style to target',
 )
+@click.option(
+    '--fix-rst-backticks',
+    default=True,
+    show_default=True,
+    help='Fix single backticks to double backticks per rST syntax',
+)
 def main(
         paths: tuple[str, ...],
         config: str | None,  # noqa: ARG001 (used by Click callback)
         exclude: str,
         line_length: int,
         docstring_style: str,
+        fix_rst_backticks: bool,
 ) -> None:
     """Format .py files."""
     ret = 0
@@ -61,7 +68,10 @@ def main(
 
     for path in paths:
         fixer = PythonFileFixer(
-            path=path, exclude_pattern=exclude, line_length=line_length
+            path=path,
+            exclude_pattern=exclude,
+            line_length=line_length,
+            fix_rst_backticks=fix_rst_backticks,
         )
         fixer.docstring_style = docstring_style
         ret |= fixer.fix_one_directory_or_one_file()
@@ -78,9 +88,11 @@ class PythonFileFixer(BaseFixer):
             path: str,
             exclude_pattern: str = r'\.git|\.tox|\.pytest_cache',
             line_length: int = 79,
+            fix_rst_backticks: bool = True,
     ) -> None:
         super().__init__(path=path, exclude_pattern=exclude_pattern)
         self.line_length = line_length
+        self.fix_rst_backticks = fix_rst_backticks
         self.docstring_style: str = 'numpy'
 
     def fix_one_file(self, filename: str) -> int:
@@ -109,6 +121,7 @@ class PythonFileFixer(BaseFixer):
             source_text,
             line_length=self.line_length,
             docstring_style=self.docstring_style,
+            fix_rst_backticks=self.fix_rst_backticks,
         )
 
         if filename == '-':

{format_docstring-0.1.4 → format_docstring-0.1.6}/format_docstring.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.1.4
+Version: 0.1.6
 Summary: A Python formatter to wrap/adjust docstring lines
 Author-email: jsh9 <25124332+jsh9@users.noreply.github.com>
 Maintainer-email: jsh9 <25124332+jsh9@users.noreply.github.com>
@@ -45,6 +45,7 @@ A Python formatter to automatically format numpy-style docstrings.
   - [2.2. One-line summaries are formatted to fit line length limit](#22-one-line-summaries-are-formatted-to-fit-line-length-limit)
   - [2.3. Minor typos can be automatically fixed](#23-minor-typos-can-be-automatically-fixed)
   - [2.4. Default value declarations are standardized](#24-default-value-declarations-are-standardized)
+  - [2.5. Single backticks are converted to double backticks (rST syntax)](#25-single-backticks-are-converted-to-double-backticks-rst-syntax)
 - [3. Installation](#3-installation)
 - [4. Usage](#4-usage)
   - [4.1. Command Line Interface](#41-command-line-interface)
@@ -209,6 +210,29 @@ def example_function(arg1, arg2, arg3, arg4):
     pass
 ```
 
+### 2.5. Single backticks are converted to double backticks (rST syntax)
+
+```diff
+def process_data(data):
+    """
+-    Process data using the `transform` function.
++    Process data using the ``transform`` function.
+
+    Parameters
+    ----------
+    data : dict
+-        Input data with keys `id`, `value`, and `timestamp`.
++        Input data with keys ``id``, ``value``, and ``timestamp``.
+
+    Returns
+    -------
+    dict
+-        Processed data with key `result`.
++        Processed data with key ``result``.
+    """
+    pass
+```
+
 ## 3. Installation
 
 ```bash
@@ -265,6 +289,8 @@ pre-commit install
   (default: 79)
 - `--docstring-style CHOICE`: Docstring style to target (`numpy` or `google`,
   default: `numpy`). Note: Currently only `numpy` style is fully supported.
+- `--fix-rst-backticks BOOL`: Automatically fix single backticks to double
+  backticks per rST syntax (default: True)
 - `--exclude TEXT`: Regex pattern to exclude files/directories (default:
   `\.git|\.tox|\.pytest_cache`)
 - `--config PATH`: Path to a `pyproject.toml` config file. If not specified,
@@ -290,6 +316,9 @@ format-docstring --config path/to/pyproject.toml src/
 
 # CLI options override config file settings
 format-docstring --config pyproject.toml --line-length 100 src/
+
+# Disable backtick fixing
+format-docstring --fix-rst-backticks=False my_module.py
 ```
 
 ### 5.3. `pyproject.toml` Configuration
@@ -301,6 +330,7 @@ override these settings:
 [tool.format_docstring]
 line_length = 79
 docstring_style = "numpy"
+fix_rst_backticks = true
 exclude = "\\.git|\\.venv|__pycache__"
 ```
 
@@ -310,6 +340,8 @@ exclude = "\\.git|\\.venv|__pycache__"
   79\)
 - `docstring_style` (str): Docstring style, either `"numpy"` or `"google"`
   (default: `"numpy"`)
+- `fix_rst_backticks` (bool): Automatically fix single backticks to double
+  backticks per rST syntax (default: `true`)
 - `exclude` (str): Regex pattern to exclude files/directories (default:
   `"\\.git|\\.tox|\\.pytest_cache"`)
 

{format_docstring-0.1.4 → format_docstring-0.1.6}/format_docstring.egg-info/SOURCES.txt

@@ -44,6 +44,7 @@ tests/test_data/end_to_end/numpy/default_value_standardization.txt
 tests/test_data/end_to_end/numpy/empty_lines_are_respected.txt
 tests/test_data/end_to_end/numpy/examples_section.txt
 tests/test_data/end_to_end/numpy/existing_linebreaks_should_not_be_respected.txt
+tests/test_data/end_to_end/numpy/fix_rst_backticks.txt
 tests/test_data/end_to_end/numpy/four_level_nested_classes.txt
 tests/test_data/end_to_end/numpy/indent_four_levels_16_spaces_width_10.txt
 tests/test_data/end_to_end/numpy/indent_misaligned_all.txt
@@ -76,6 +77,7 @@ tests/test_data/line_wrap/numpy/default_value_standardization.txt
 tests/test_data/line_wrap/numpy/empty_lines_are_respected.txt
 tests/test_data/line_wrap/numpy/examples_section.txt
 tests/test_data/line_wrap/numpy/existing_linebreaks_should_not_be_respected.txt
+tests/test_data/line_wrap/numpy/fix_rst_backticks.txt
 tests/test_data/line_wrap/numpy/indent_four_levels_16_spaces_width_10.txt
 tests/test_data/line_wrap/numpy/indent_two_levels_8_spaces.txt
 tests/test_data/line_wrap/numpy/line_length_2.txt

{format_docstring-0.1.4 → format_docstring-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "format-docstring"
-version = "0.1.4"
+version = "0.1.6"
 description = "A Python formatter to wrap/adjust docstring lines"
 readme = "README.md"
 license = {text = "MIT"}