Antsibull Docutils Helpers

1.4.0 · active · verified Thu Apr 16

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.

Common errors

```
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`.
```
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.

Install

pip install antsibull-docutils Install latest version

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("---")

view raw JSON →