{"id":8829,"library":"antsibull-docutils","title":"Antsibull Docutils Helpers","description":"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.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/ansible-community/antsibull-docutils","tags":["ansible","documentation","docutils","sphinx","rst"],"install":[{"cmd":"pip install antsibull-docutils","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core 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.","package":"docutils","optional":false}],"imports":[{"note":"A primary helper function for identifying code blocks in RST content.","symbol":"find_code_blocks","correct":"from antsibull_docutils.rst_code_finder import find_code_blocks"}],"quickstart":{"code":"from antsibull_docutils.rst_code_finder import find_code_blocks\n\nrst_content = '''\n.. code-block:: python\n\n    print(\"Hello from Python!\")\n\nA normal paragraph.\n\n.. code-block:: yaml\n\n    - name: Example task\n      ansible.builtin.debug:\n        msg: \"YAML here\"\n'''\n\ncode_blocks = find_code_blocks(rst_content)\n\nfor block in code_blocks:\n    print(f\"Found code block (type: {block.directive_arg}, line {block.line_number}):\")\n    print(block.code)\n    print(\"---\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure `docutils` version 0.18 or newer is installed and used in your environment (`pip install 'docutils>=0.18'`).","message":"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.","severity":"gotcha","affected_versions":"<1.0.0 (and potentially current versions when used with old docutils)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Correct the import path to `from antsibull_docutils.rst_code_finder import find_code_blocks`.","cause":"The `find_code_blocks` function is nested within the `rst_code_finder` submodule.","error":"TypeError: 'module' object is not callable (e.g., trying antsibull_docutils.find_code_blocks(...))"},{"fix":"Upgrade your `docutils` installation to version 0.18 or newer (`pip install --upgrade 'docutils>=0.18'`).","cause":"This often occurs when using an incompatible or outdated version of the `docutils` library, especially versions 0.16 or 0.17.","error":"Docutils-related rendering issues (e.g., unexpected HTML output, missing code blocks, incorrect IDs) when processing RST."}]}