Merge pull request #384 from adamtheturtle/document-invisible

Support using invisible code blocks as a way to add newlines for formatters

README.rst

@@ -119,6 +119,7 @@ Running linters with ``doccmd`` gives you errors and warnings with line numbers
 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`` and ``--no-pad-groups`` flag.
+See using_groups_with_formatters_ for more information.
 
 File names and linter ignores
 -----------------------------
@@ -227,6 +228,7 @@ You might have two code blocks like this:
    def my_function() -> None:
        """Do nothing."""
 
+.. invisible-code-block: python
 
 .. code-block:: python
 
@@ -244,6 +246,34 @@ Error messages for grouped code blocks may include lines which do not match the
 Use the ``--group-marker`` option to set a marker for this particular command which will work as well as ``all``.
 For example, use ``--group-marker="type-check"`` to group code blocks which come between comments matching ``group doccmd[type-check]: start`` and ``group doccmd[type-check]: end``.
 
+.. _using_groups_with_formatters:
+
+Using groups with formatters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, code blocks in groups will be separated by newlines in the temporary file created.
+This means that line numbers from the original document match the line numbers in the temporary file, and error messages will have correct line numbers.
+Some tools, such as formatters, may not work well with this separation.
+To have just one newline between code blocks in a group, use the ``--no-pad-groups`` option.
+If you then want to add extra padding to the code blocks in a group, add invisible code blocks to the document.
+Make sure that the language of the invisible code block is the same as the ``--language`` option given to ``doccmd``.
+
+For example:
+
+* reStructuredText (``.rst``)
+
+.. code-block:: rst
+
+   .. invisible-code-block: java
+
+* Markdown (``.md``)
+
+.. code-block:: markdown
+
+   <!-- invisible-code-block: java
+
+   -->
+
 Full documentation
 ------------------
 

docs/source/group-code-blocks.rst

@@ -28,3 +28,31 @@ Error messages for grouped code blocks may include lines which do not match the
 
 Use the ``--group-marker`` option to set a marker for this particular command which will work as well as ``all``.
 For example, use ``--group-marker="type-check"`` to group code blocks which come between comments matching ``group doccmd[type-check]: start`` and ``group doccmd[type-check]: end``.
+
+.. _using_groups_with_formatters:
+
+Using groups with formatters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, code blocks in groups will be separated by newlines in the temporary file created.
+This means that line numbers from the original document match the line numbers in the temporary file, and error messages will have correct line numbers.
+Some tools, such as formatters, may not work well with this separation.
+To have just one newline between code blocks in a group, use the ``--no-pad-groups`` option.
+If you then want to add extra padding to the code blocks in a group, add invisible code blocks to the document.
+Make sure that the language of the invisible code block is the same as the ``--language`` option given to ``doccmd``.
+
+For example:
+
+* reStructuredText (``.rst``)
+
+.. code-block:: rst
+
+   .. invisible-code-block: java
+
+* Markdown (``.md``)
+
+.. code-block:: markdown
+
+   <!-- invisible-code-block: java
+
+   -->

docs/source/index.rst

@@ -49,6 +49,7 @@ Running linters with ``doccmd`` gives you errors and warnings with line numbers
 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`` and ``--no-pad-groups`` flags.
+See :ref:`using_groups_with_formatters` for more information.
 
 .. include:: file-names-and-linter-ignores.rst
 

pyproject.toml

@@ -44,7 +44,7 @@ dependencies = [
     # Pin this dependency as we expect:
     # * It might have breaking changes
     # * It is not a direct dependency of the user
-    "sybil-extras==2025.2.27.1",
+    "sybil-extras==2025.2.28.1",
 ]
 optional-dependencies.dev = [
     "actionlint-py==1.7.7.23",