Use antsibull-docs-parser for markup processing (#124)

* Use antsibull-docs-parser for markup processing.

* Bump antsibull-docs-parser version to 0.3.0.

* Fix grammar.

Co-authored-by: Maxwell G <[email protected]>

* Make sure to check out and install local antsibull-docs-parser.

---------

Co-authored-by: Maxwell G <[email protected]>

Author: felixfontein

.github/workflows/antsibull-docs.yml

@@ -33,6 +33,8 @@ jobs:
           - '3.11'
         antsibull_core_ref:
           - main
+        antsibull_docs_parser_ref:
+          - main
         include:
           - options: '--use-current --use-html-blobs --no-breadcrumbs community.crypto community.docker'
             python: '3.9'
@@ -51,6 +53,13 @@ jobs:
           path: antsibull-core
           ref: ${{ matrix.antsibull_core_ref }}
 
+      - name: Check out dependent project antsibull-docs-parser
+        uses: actions/checkout@v3
+        with:
+          repository: ansible-community/antsibull-docs-parser
+          path: antsibull-docs-parser
+          ref: ${{ matrix.antsibull_docs_parser_ref }}
+
       - name: Set up Python ${{ matrix.python }}
         uses: actions/setup-python@v4
         with:
@@ -59,7 +68,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .[coverage] ../antsibull-core
+          pip install -e .[coverage] ../antsibull-core ../antsibull-docs-parser
         working-directory: antsibull-docs
 
       - name: Use antsibull-docs sphinx-init
@@ -147,6 +156,12 @@ jobs:
           repository: ansible-community/antsibull-core
           path: antsibull-core
 
+      - name: Check out dependent project antsibull-docs-parser
+        uses: actions/checkout@v3
+        with:
+          repository: ansible-community/antsibull-docs-parser
+          path: antsibull-docs-parser
+
       - name: Set up Python 3.11
         uses: actions/setup-python@v4
         with:
@@ -155,7 +170,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .[coverage] ../antsibull-core
+          pip install -e .[coverage] ../antsibull-core ../antsibull-docs-parser
         working-directory: antsibull-docs
 
       - name: Get hold of deps file
@@ -197,6 +212,12 @@ jobs:
           repository: ansible-community/antsibull-core
           path: antsibull-core
 
+      - name: Check out dependent project antsibull-docs-parser
+        uses: actions/checkout@v3
+        with:
+          repository: ansible-community/antsibull-docs-parser
+          path: antsibull-docs-parser
+
       - name: Set up Python 3.11
         uses: actions/setup-python@v4
         with:
@@ -205,7 +226,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .[coverage] ../antsibull-core
+          pip install -e .[coverage] ../antsibull-core ../antsibull-docs-parser
         working-directory: antsibull-docs
 
       - name: Get hold of ansible.in file

.github/workflows/nox.yml

@@ -35,6 +35,11 @@ jobs:
         with:
           repository: ansible-community/antsibull-core
           path: antsibull-core
+      - name: Check out dependent project antsibull-docs-parser
+        uses: actions/checkout@v3
+        with:
+          repository: ansible-community/antsibull-docs-parser
+          path: antsibull-docs-parser
       - name: Setup nox
         uses: wntrblm/[email protected]
         with:
@@ -56,6 +61,11 @@ jobs:
         with:
           repository: ansible-community/antsibull-core
           path: antsibull-core
+      - name: Check out dependent project antsibull-docs-parser
+        uses: actions/checkout@v3
+        with:
+          repository: ansible-community/antsibull-docs-parser
+          path: antsibull-docs-parser
       - name: Setup nox
         uses: wntrblm/[email protected]
         with:

README.md

@@ -71,19 +71,19 @@ and install the requirements needed to run the tests there.
 
 ---
 
-antsibull-docs depends on the sister antsibull-core project.
-By default, `nox` will install a development version of this project from
+antsibull-docs depends on the sister antsibull-core and antsibull-docs-parser projects.
+By default, `nox` will install a development version of these projects from
 Github.
-If you're hacking on antsibull-core alongside antsibull-docs, nox will automatically
-install the project from `../antsibull-core` when running tests if those paths
-exist.
+If you're hacking on antsibull-core and/or antsibull-docs-parser alongside antsibull-docs,
+nox will automatically install the projects from `../antsibull-core` and
+`../antsibull-docs-parser` when running tests if those paths exist.
 You can change this behavior through the `OTHER_ANTSIBULL_MODE` env var:
 
 - `OTHER_ANTSIBULL_MODE=auto` — the default behavior described above
-- `OTHER_ANTSIBULL_MODE=local` — install the project from `../antsibull-core`.
-  Fail if that paths doesn't exist.
+- `OTHER_ANTSIBULL_MODE=local` — install the projects from `../antsibull-core`
+  and `../antsibull-docs-parser`. Fail if those paths don't exist.
 - `OTHER_ANTSIBULL_MODE=git` — install the projects from the Github main branch
-- `OTHER_ANTSIBULL_MODE=pypi` — install the latest version from PyPI
+- `OTHER_ANTSIBULL_MODE=pypi` — install the latest versions from PyPI
 
 
 To run specific tests:
@@ -97,11 +97,12 @@ To create a more complete local development env:
 
 ``` console
 git clone https://github.com/ansible-community/antsibull-core.git
+git clone https://github.com/ansible-community/antsibull-docs-parser.git
 git clone https://github.com/ansible-community/antsibull-docs.git
 cd antsibull-docs
 python3 -m venv venv
 . ./venv/bin/activate
-pip install -e '.[dev]' -e ../antsibull-core
+pip install -e '.[dev]' -e ../antsibull-core -e ../antsibull-docs-parser
 [...]
 nox
 ```

changelogs/fragments/124-antsibull-docs-parser.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "The dependency `antsibull-docs-parser <https://github.com/ansible-community/antsibull-docs-parser>`__ has been added and is used for processing Ansible markup (https://github.com/ansible-community/antsibull-docs/pull/124)."

noxfile.py

@@ -40,7 +40,7 @@ def other_antsibull(
     if mode is None:
         mode = DEFAULT_MODE
     to_install: list[str | Path] = []
-    args = ("antsibull-core", )
+    args = ("antsibull-core", "antsibull-docs-parser")
     for project in args:
         path = Path("../", project)
         path_exists = path.is_dir()

pyproject.toml

@@ -26,6 +26,7 @@ requires-python = ">=3.9"
 dependencies = [
     "ansible-pygments",
     "antsibull-core >= 1.2.0, < 3.0.0",
+    "antsibull-docs-parser ~= 0.3.0",
     "asyncio-pool",
     "docutils",
     "jinja2 >= 3.0",

src/antsibull_docs/lint_plugin_docs.py

@@ -17,6 +17,10 @@
 from antsibull_core.vendored.json_utils import _filter_non_json_lines
 from antsibull_core.venv import FakeVenvRunner
 
+from antsibull_docs_parser import dom
+from antsibull_docs_parser.parser import Context as ParserContext
+from antsibull_docs_parser.parser import parse as parse_markup
+
 from sphinx_antsibull_ext import roles as antsibull_roles
 
 from .augment_docs import augment_docs
@@ -31,9 +35,6 @@
 from .docs_parsing.routing import load_all_collection_routing, remove_redirect_duplicates
 from .jinja2.environment import doc_environment
 from .lint_helpers import load_collection_info
-from .markup import dom
-from .markup.parser import Context as ParserContext
-from .markup.parser import parse as parse_markup
 from .rstcheck import check_rst_content
 from .utils.collection_name_transformer import CollectionNameTransformer
 from .write_docs.plugins import create_plugin_rst, guess_relative_filename, has_broken_docs

src/antsibull_docs/markup/_counter.py

@@ -9,7 +9,7 @@
 
 import typing as t
 
-from . import dom
+from antsibull_docs_parser import dom
 
 
 class _Counter(dom.Walker):