{"id":6514,"library":"antsibull-docs-parser","title":"antsibull-docs-parser","description":"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.","status":"active","version":"1.2.2","language":"en","source_language":"en","source_url":"https://github.com/ansible-community/antsibull-docs-parser","tags":["ansible","documentation","parser","markup","rst"],"install":[{"cmd":"pip install antsibull-docs-parser","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"parse","correct":"from antsibull_docs_parser.parser import parse"},{"note":"Used to customize parsing behavior, e.g., for different output formats or link providers.","symbol":"BaseContext","correct":"from antsibull_docs_parser.parser import BaseContext"},{"note":"Function to convert a parsed DOM to plain text.","symbol":"to_text","correct":"from antsibull_docs_parser.formatters import to_text"},{"note":"Function to convert a parsed DOM to reStructuredText (RST).","symbol":"to_rst","correct":"from antsibull_docs_parser.formatters import to_rst"}],"quickstart":{"code":"from antsibull_docs_parser.parser import parse\nfrom antsibull_docs_parser.formatters import to_text\n\nansible_markup = \"This is some B(bold) text and C(code). Here's a M(ansible.builtin.debug) module reference.\"\n\n# Parse the Ansible markup string into a Document Object Model (DOM)\ndom = parse(ansible_markup)\n\n# The DOM is a list of nodes, typically Paragraph objects\nprint(f\"Parsed DOM type: {type(dom)}\")\nfor node in dom:\n    print(f\"  Node type: {type(node)}\")\n    # Example: print a specific node representation\n    # print(node.to_text())\n\n# Convert the parsed DOM to plain text\nplain_text = to_text(dom)\nprint(f\"\\nPlain text output: {plain_text}\")\n\n# Example of accessing DOM structure (simplified)\n# This is a conceptual demonstration; actual DOM traversal depends on use case\nif dom and hasattr(dom[0], 'parts'): # Assuming the first element is a Paragraph with parts\n    print(\"\\nFirst paragraph parts:\")\n    for part in dom[0].parts:\n        print(f\"  - {type(part).__name__}: '{getattr(part, 'text', str(part))}'\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer.","message":"Python 3.6, 3.7, and 3.8 are no longer supported. Python 3.9 or newer is now required.","severity":"breaking","affected_versions":"<1.2.0 (specifically older versions before 1.2.0 dropped support)"},{"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.","message":"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.","severity":"breaking","affected_versions":"0.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the package using pip: 'pip install antsibull-docs-parser'.","cause":"The 'antsibull-docs-parser' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'antsibull_docs_parser'"},{"fix":"Ensure that the function exists in the module and that the import statement is correct: 'from antsibull_docs_parser import parse'.","cause":"The 'parse' function is not available in the 'antsibull_docs_parser' module, possibly due to an incorrect import statement or a missing function.","error":"ImportError: cannot import name 'parse' from 'antsibull_docs_parser'"},{"fix":"Verify the module's documentation for the correct function name and usage.","cause":"The 'toHTML' function does not exist in the 'antsibull_docs_parser' module.","error":"AttributeError: module 'antsibull_docs_parser' has no attribute 'toHTML'"},{"fix":"Provide the necessary 'walker' argument when calling 'walk': 'walk(paragraph, walker)'.","cause":"The 'walk' function was called without the required 'walker' argument.","error":"TypeError: walk() missing 1 required positional argument: 'walker'"},{"fix":"Ensure that all 'PartType' values are correctly defined and handled in the code.","cause":"An unrecognized 'PartType' was encountered during processing.","error":"RuntimeError: Internal error: unknown type 'PartType.UNKNOWN'"}]}