Install & Compatibility
Where this runs
tested against v1.2.2 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.035s · 18MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.5s · import 0.027s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse
✓ from antsibull_docs_parser.parser import parse
BaseContext
✓ from antsibull_docs_parser.parser import BaseContext
Used to customize parsing behavior, e.g., for different output formats or link providers.
to_text
✓ from antsibull_docs_parser.formatters import to_text
Function to convert a parsed DOM to plain text.
to_rst
✓ from antsibull_docs_parser.formatters import to_rst
Function to convert a parsed DOM to reStructuredText (RST).
This quickstart demonstrates how to parse a simple Ansible documentation markup string using `antsibull-docs-parser` and then convert the resulting Document Object Model (DOM) into a plain text representation. It also shows a basic way to inspect the structure of the parsed DOM. The `parse` function is the main entry point, returning a list of DOM elements.
from antsibull_docs_parser.parser import parse
from antsibull_docs_parser.formatters import to_text
ansible_markup = "This is some B(bold) text and C(code). Here's a M(ansible.builtin.debug) module reference."
# Parse the Ansible markup string into a Document Object Model (DOM)
dom = parse(ansible_markup)
# The DOM is a list of nodes, typically Paragraph objects
print(f"Parsed DOM type: {type(dom)}")
for node in dom:
print(f" Node type: {type(node)}")
# Example: print a specific node representation
# print(node.to_text())
# Convert the parsed DOM to plain text
plain_text = to_text(dom)
print(f"\nPlain text output: {plain_text}")
# Example of accessing DOM structure (simplified)
# This is a conceptual demonstration; actual DOM traversal depends on use case
if dom and hasattr(dom[0], 'parts'): # Assuming the first element is a Paragraph with parts
print("\nFirst paragraph parts:")
for part in dom[0].parts:
print(f" - {type(part).__name__}: '{getattr(part, 'text', str(part))}'")
Debug
Known issues
breakingPython 3.6, 3.7, and 3.8 are no longer supported. Python 3.9 or newer is now required.fixUpgrade your Python environment to 3.9 or newer.
affects: <1.2.0 (specifically older versions before 1.2.0 dropped support)
breakingIn `v0.2.0`, several internal DOM named tuples were changed to include a `source` entry. Error messages also started containing the full faulty markup command by default. The `CommandParser.parse` function gained a new `source` parameter, and the `LinkProvider.plugin_option_like_link` signature was modified to include an `entrypoint` argument. These changes might affect consumers directly interacting with the DOM structure or advanced parser options.fixReview code that directly manipulates DOM elements, custom `CommandParser` usage, or `LinkProvider` implementations. Adjust parameter calls and attribute access according to the `v0.2.0` release notes.
affects: 0.2.0
gotchaThe library primarily provides a generic API for parsing and processing Ansible markup. While it integrates with `antsibull-docs` for generating Sphinx output, using `antsibull-docs-parser` as a standalone library for complex documentation generation might require custom formatting and context handling beyond simple `to_text` or `to_rst` conversions.fixConsult the 'Python API' and 'Specification' sections of the official documentation for detailed understanding of DOM structure and advanced usage. Consider `antsibull-docs` if a complete documentation build solution is needed.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'antsibull_docs_parser'
The 'antsibull-docs-parser' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install antsibull-docs-parser'.
ImportError: cannot import name 'parse' from 'antsibull_docs_parser'
The 'parse' function is not available in the 'antsibull_docs_parser' module, possibly due to an incorrect import statement or a missing function.
fixEnsure that the function exists in the module and that the import statement is correct: 'from antsibull_docs_parser import parse'.
AttributeError: module 'antsibull_docs_parser' has no attribute 'toHTML'
The 'toHTML' function does not exist in the 'antsibull_docs_parser' module.
fixVerify the module's documentation for the correct function name and usage.
TypeError: walk() missing 1 required positional argument: 'walker'
The 'walk' function was called without the required 'walker' argument.
fixProvide the necessary 'walker' argument when calling 'walk': 'walk(paragraph, walker)'.
RuntimeError: Internal error: unknown type 'PartType.UNKNOWN'
An unrecognized 'PartType' was encountered during processing.
fixEnsure that all 'PartType' values are correctly defined and handled in the code.
Upgrade
Version history
1.2.2latest on PyPI · released Sep 28, 2025
Audit
Dependencies
No dependency data recorded yet.