Merge pull request #383 from adamtheturtle/pad-groups-option

Add option to pad groups or not

README.rst

@@ -118,7 +118,7 @@ Formatters and padding
 Running linters with ``doccmd`` gives you errors and warnings with line numbers that match the documentation file.
 It does this by adding padding to the code blocks before running the command.
 
-Some tools do not work well with this padding, and you can choose to obscure the line numbers in order to give the tool the original code block's content without padding, by using the ``--no-pad-file`` flag.
+Some tools do not work well with this padding, and you can choose to obscure the line numbers in order to give the tool the original code block's content without padding, by using the ``--no-pad-file`` and ``--no-pad-groups`` flag.
 
 File names and linter ignores
 -----------------------------
@@ -223,6 +223,7 @@ You might have two code blocks like this:
 
    """Example function which is used in a future code block."""
 
+
    def my_function() -> None:
        """Do nothing."""
 

docs/source/index.rst

@@ -48,7 +48,7 @@ Formatters and padding
 Running linters with ``doccmd`` gives you errors and warnings with line numbers that match the documentation file.
 It does this by adding padding to the code blocks before running the command.
 
-Some tools do not work well with this padding, and you can choose to obscure the line numbers in order to give the tool the original code block's content without padding, by using the ``--no-pad-file`` flag.
+Some tools do not work well with this padding, and you can choose to obscure the line numbers in order to give the tool the original code block's content without padding, by using the ``--no-pad-file`` and ``--no-pad-groups`` flags.
 
 .. include:: file-names-and-linter-ignores.rst
 

src/doccmd/__init__.py

@@ -410,6 +410,7 @@ def _run_args_against_docs(
     temporary_file_extension: str | None,
     temporary_file_name_prefix: str | None,
     pad_temporary_file: bool,
+    pad_groups: bool,
     verbose: bool,
     skip_markers: Iterable[str],
     group_markers: Iterable[str],
@@ -498,7 +499,7 @@ def _run_args_against_docs(
         markup_language.group_parser_cls(
             directive=group_directive,
             evaluator=group_evaluator,
-            pad_groups=True,
+            pad_groups=pad_groups,
         )
         for group_directive in group_directives
     ]
@@ -634,6 +635,20 @@ def _run_args_against_docs(
         "they generally need to look at the file without padding."
     ),
 )
+@click.option(
+    "--pad-groups/--no-pad-groups",
+    is_flag=True,
+    default=True,
+    show_default=True,
+    help=(
+        "Maintain line spacing between groups from the source file in the "
+        "temporary file. "
+        "This is useful for matching line numbers from the output to "
+        "the relevant location in the document. "
+        "Use --no-pad-groups for formatters - "
+        "they generally need to look at the file without padding."
+    ),
+)
 @click.argument(
     "document_paths",
     type=click.Path(exists=True, path_type=Path, dir_okay=True),
@@ -773,6 +788,7 @@ def main(
     temporary_file_extension: str | None,
     temporary_file_name_prefix: str | None,
     pad_file: bool,
+    pad_groups: bool,
     verbose: bool,
     skip_markers: Sequence[str],
     group_markers: Sequence[str],
@@ -835,6 +851,7 @@ def main(
                     document_path=file_path,
                     code_block_language=code_block_language,
                     pad_temporary_file=pad_file,
+                    pad_groups=pad_groups,
                     verbose=verbose,
                     temporary_file_extension=temporary_file_extension,
                     temporary_file_name_prefix=temporary_file_name_prefix,

tests/test_doccmd.py

@@ -2708,11 +2708,21 @@ def test_lexing_exception(
         ("custom-marker", ["--group-marker", "custom-marker"]),
     ],
 )
+@pytest.mark.parametrize(
+    argnames=("group_padding_options", "expect_padding"),
+    argvalues=[
+        ([], True),
+        (["--no-pad-groups"], False),
+    ],
+)
 def test_group_blocks(
+    *,
     tmp_path: Path,
     file_padding_options: Sequence[str],
     group_marker: str,
     group_marker_options: Sequence[str],
+    group_padding_options: Sequence[str],
+    expect_padding: bool,
 ) -> None:
     """It is possible to group some blocks together.
 
@@ -2762,6 +2772,7 @@ def test_group_blocks(
 
     arguments = [
         *file_padding_options,
+        *group_padding_options,
         *group_marker_options,
         "--language",
         "python",
@@ -2776,20 +2787,34 @@ def test_group_blocks(
     )
     # The expected output is that the content outside the group remains
     # unchanged, while the contents inside the group are merged.
-    expected_output = textwrap.dedent(
-        text="""\
-        block_1
-        -------
-        block_group_1
+    if expect_padding:
+        expected_output = textwrap.dedent(
+            text="""\
+            block_1
+            -------
+            block_group_1
 
 
 
-        block_group_2
-        -------
-        block_3
-        -------
-        """,
-    )
+            block_group_2
+            -------
+            block_3
+            -------
+            """,
+        )
+    else:
+        expected_output = textwrap.dedent(
+            text="""\
+            block_1
+            -------
+            block_group_1
+
+            block_group_2
+            -------
+            block_3
+            -------
+            """,
+        )
     assert result.exit_code == 0, (result.stdout, result.stderr)
     assert result.stdout == expected_output
     assert result.stderr == ""

tests/test_doccmd/test_help.txt

@@ -72,6 +72,13 @@ Options:
                                   pad-file for formatters - they generally need
                                   to look at the file without padding.
                                   [default: pad-file]
+  --pad-groups / --no-pad-groups  Maintain line spacing between groups from the
+                                  source file in the temporary file. This is
+                                  useful for matching line numbers from the
+                                  output to the relevant location in the
+                                  document. Use --no-pad-groups for formatters -
+                                  they generally need to look at the file
+                                  without padding.  [default: pad-groups]
   --version                       Show the version and exit.
   -v, --verbose                   Enable verbose output.
   --use-pty                       Use a pseudo-terminal for running commands.