Registry / devops / antsibull-docutils

antsibull-docutils

library1.4.0pypypi✓ verified 85d ago

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.

devops

pip install antsibull-docutils

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · ANTSIBULL-DOCUTILS

antsibull-docutils

devopspythonv1.4.0

Install

1.9s avg

Import

140ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.147s · 22.3MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.9s · import 0.133s · 23MB

21MB installed

● package 21MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

find_code_blocks

✓ from antsibull_docutils.rst_code_finder import find_code_blocks

A primary helper function for identifying code blocks in RST content.

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

Debug

Known issues

gotchaCompatibility 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'`).

affects: <1.0.0 (and potentially current versions when used with old docutils)

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

affects: All versions

Errors

Common errors & fixes

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

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.

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

Upgrade

Version history

1.4.0latest on PyPI · released Dec 27, 2025

Audit

Dependencies

docutilsrequiredCore functionality relies on docutils for parsing RST. Compatibility is explicitly tested with docutils 0.18+, and older versions (0.16, 0.17) are known to have rendering issues.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ansible-community/antsibull-docutils ↗

packagehttps://pypi.org/project/antsibull-docutils/ ↗

changeloghttps://github.com/ansible-community/antsibull-docutils/tree/main/CHANGELOG.md ↗