Skipping code blocksΒΆ

Code blocks which come just after a comment matching skip doccmd[all]: next are skipped.

To skip multiple code blocks in a row, use skip doccmd[all]: start and skip doccmd[all]: end comments surrounding the code blocks to skip.

Use the --skip-marker option to set a marker for this particular command which will work as well as all. For example, use --skip-marker="type-check" to skip code blocks which come just after a comment matching skip doccmd[type-check]: next.

To skip a code block for each of multiple markers, for example to skip a code block for the type-check and lint markers but not all markers, add multiple skip doccmd comments above the code block.

The skip comment will skip the next code block which would otherwise be run. This means that if you run doccmd with --language=python, the Python code block in the following example will be skipped:

<-- skip doccmd[all]: next -->

```{code-block} shell
echo "This will not run because the shell language was not selected"
```

```{code-block} python
print("This will be skipped!")
```

Therefore it is not recommended to use skip doccmd[all] and to instead use a more specific marker. For example, if we used doccmd with --language=shell and --skip-marker=echo the following examples show how to skip code blocks in different formats:

  • reStructuredText (.rst)

.. skip doccmd[echo]: next

.. code-block:: shell

   echo "This will be skipped!"

.. code-block:: shell

   echo "This will run"

  • Markdown (.md)

<-- skip doccmd[echo]: next -->

```shell
echo "This will be skipped!"
```

```shell
echo "This will run"
```

  • MyST (.md with MyST syntax)

% skip doccmd[echo]: next

```{code-block} shell
echo "This will be skipped!"
```

```{code-block} shell
echo "This will run"
```