antsibull-docs-parser

1.2.2 verified Wed Apr 15 auth: no python

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.

pip install antsibull-docs-parser

Common errors

error 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'.

error 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'.

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

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

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

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