antsibull-docs-parser

1.2.2 · active · verified Wed Apr 15

A Python library for processing Ansible documentation markup, designed for reusability. It originates from `antsibull-docs` and provides a generic API to parse, process, and format Ansible markup. The library is currently at version 1.2.2 and adheres to semantic versioning, with major version 1.x.y releases ensuring no breaking changes to its API.

Common errors

```
ModuleNotFoundError: No module named 'antsibull_docs_parser'
```
cause The 'antsibull-docs-parser' package is not installed in the Python environment.

fix Install the package using pip: 'pip install antsibull-docs-parser'.
```
ImportError: cannot import name 'parse' from 'antsibull_docs_parser'
```
cause The 'parse' function is not available in the 'antsibull_docs_parser' module, possibly due to an incorrect import statement or a missing function.

fix Ensure 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'
```
cause The 'toHTML' function does not exist in the 'antsibull_docs_parser' module.

fix Verify the module's documentation for the correct function name and usage.
```
TypeError: walk() missing 1 required positional argument: 'walker'
```
cause The 'walk' function was called without the required 'walker' argument.

fix Provide the necessary 'walker' argument when calling 'walk': 'walk(paragraph, walker)'.
```
RuntimeError: Internal error: unknown type 'PartType.UNKNOWN'
```
cause An unrecognized 'PartType' was encountered during processing.

fix Ensure that all 'PartType' values are correctly defined and handled in the code.

Warnings

breaking Python 3.6, 3.7, and 3.8 are no longer supported. Python 3.9 or newer is now required.
Fix: Upgrade your Python environment to 3.9 or newer.
breaking In `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.
Fix: Review 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.
gotcha The 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.
Fix: Consult 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.

Install

pip install antsibull-docs-parser Install stable version

Imports

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

Quickstart

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))}'")

view raw JSON →