Antsibull Docutils Helpers

1.4.0 verified Thu Apr 16 auth: no python

Antsibull-docutils is a Python library that provides docutils helpers used primarily by other Antsibull tools for building Ansible documentation. It offers functionalities like finding code blocks within reStructuredText (RST) files. The library is currently at version 1.4.0 and is actively maintained within the Ansible community, showing a regular release cadence with recent updates.

pip install antsibull-docutils

Common errors

error TypeError: 'module' object is not callable (e.g., trying antsibull_docutils.find_code_blocks(...)) ↓

cause The `find_code_blocks` function is nested within the `rst_code_finder` submodule.

fix

Correct the import path to from antsibull_docutils.rst_code_finder import find_code_blocks.

error Docutils-related rendering issues (e.g., unexpected HTML output, missing code blocks, incorrect IDs) when processing RST. ↓

cause This often occurs when using an incompatible or outdated version of the `docutils` library, especially versions 0.16 or 0.17.

fix

Upgrade your docutils installation to version 0.18 or newer (pip install --upgrade 'docutils>=0.18').

Warnings

gotcha Compatibility with Docutils versions older than 0.18 (specifically 0.16 and 0.17) is not guaranteed and can lead to incorrect rendering of HTML, different IDs, and issues with code block emission for Markdown renderers. ↓

fix Ensure `docutils` version 0.18 or newer is installed and used in your environment (`pip install 'docutils>=0.18'`).

gotcha Antsibull-docutils is primarily a helper library intended for use by other 'antsibull' projects (e.g., `antsibull-docs`, `antsibull-changelog`). While some functions can be used independently, its design assumes integration within the broader Ansible documentation tooling ecosystem. ↓

fix Understand its role within the Ansible community's documentation build pipeline. For general Sphinx/docutils use, consider direct `docutils` or `sphinx` APIs before relying heavily on this specialized library, unless integrating with Ansible-specific documentation.

Imports

find_code_blocks
```
from antsibull_docutils.rst_code_finder import find_code_blocks
```
A primary helper function for identifying code blocks in RST content.

Quickstart

This quickstart demonstrates how to use `find_code_blocks` to extract code snippets from a reStructuredText (RST) string. The function returns a list of CodeBlock objects, each containing details about the found block, such as its content, language, and line number.

from antsibull_docutils.rst_code_finder import find_code_blocks

rst_content = '''
.. code-block:: python

    print("Hello from Python!")

A normal paragraph.

.. code-block:: yaml

    - name: Example task
      ansible.builtin.debug:
        msg: "YAML here"
'''

code_blocks = find_code_blocks(rst_content)

for block in code_blocks:
    print(f"Found code block (type: {block.directive_arg}, line {block.line_number}):")
    print(block.code)
    print("---")