Correctly process Ansible markup.

.github/workflows/antsibull-build.yml

@@ -30,27 +30,31 @@ jobs:
  python: '3.9'
  antsibull_changelog_ref: 0.24.0
  antsibull_core_ref: main
+ antsibull_docs_parser_ref: 1.1.0
  antsibull_docutils_ref: 1.0.0 # isn't used by antsibull-changelog 0.24.0
  antsibull_fileutils_ref: main
  - name: Ansible 9
  options: '-e antsibull_ansible_version=9.99.0'
  python: '3.11'
  antsibull_changelog_ref: main
  antsibull_core_ref: main
+ antsibull_docs_parser_ref: main
  antsibull_docutils_ref: main
  antsibull_fileutils_ref: main
  - name: Ansible 10
  options: '-e antsibull_ansible_version=10.99.0'
  python: '3.12'
  antsibull_changelog_ref: main
  antsibull_core_ref: main
+ antsibull_docs_parser_ref: main
  antsibull_docutils_ref: main
  antsibull_fileutils_ref: main
  - name: Ansible 11
  options: '-e antsibull_ansible_version=11.99.0'
  python: '3.12'
  antsibull_changelog_ref: main
  antsibull_core_ref: main
+ antsibull_docs_parser_ref: main
  antsibull_docutils_ref: main
  antsibull_fileutils_ref: main
 
@@ -74,6 +78,13 @@ jobs:
  path: antsibull-core
  ref: ${{ matrix.antsibull_core_ref }}
 
+ - name: Check out dependent project antsibull-docs-parser
+ uses: actions/checkout@v4
+ with:
+ repository: ansible-community/antsibull-docs-parser
+ path: antsibull-docs-parser
+ ref: ${{ matrix.antsibull_docs_parser_ref }}
+
  - name: Check out dependent project antsibull-docutils
  uses: actions/checkout@v4
  with:

.github/workflows/nox.yml

@@ -69,6 +69,11 @@ jobs:
  with:
  repository: ansible-community/antsibull-changelog
  path: antsibull-changelog
+ - name: Check out dependent project antsibull-docs-parser
+ uses: actions/checkout@v4
+ with:
+ repository: ansible-community/antsibull-docs-parser
+ path: antsibull-docs-parser
  - name: Check out dependent project antsibull-docutils
  uses: actions/checkout@v4
  with:

README.md

@@ -49,19 +49,20 @@ and install the requirements needed to run the tests there.
 ---
 
 antsibull depends on the sister antsibull-core, antsibull-changelog,
-antsibull-docutils, and antsibull-fileutils projects.
+antsibull-docs-parser, antsibull-docutils, and antsibull-fileutils projects.
 By default, `nox` will install development versions of these projects from
 Github.
-If you're hacking on antsibull-core, antsibull-changelog, antsibull-docutils and/or
-antsibull-fileutils alongside antsibull,
+If you're hacking on antsibull-core, antsibull-changelog, antsibull-docs-parser,
+antsibull-docutils and/or antsibull-fileutils alongside antsibull,
 nox will automatically install the projects from `../antsibull-core`,
-`../antsibull-changelog`, `../antsibull-docutils`, and `../antsibull-fileutils`
-when running tests if those paths exist.
+`../antsibull-changelog`, `../antsibull-docs-parser`, `../antsibull-docutils`,
+and `../antsibull-fileutils` 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 projects from `../antsibull-core`,
- `../antsibull-changelog`, `../antsibull-docutils`, and `../antsibull-fileutils`.
+ `../antsibull-changelog`, `../antsibull-docs-parser`, `../antsibull-docutils`,
+ and `../antsibull-fileutils`.
  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
@@ -89,12 +90,13 @@ To create a more complete local development env:
 ``` console
 git clone https://github.com/ansible-community/antsibull-changelog.git
 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-docutils.git
 git clone https://github.com/ansible-community/antsibull.git
 cd antsibull
 python3 -m venv venv
 . ./venv/bin/activate
-pip install -e '.[dev]' -e ../antsibull-changelog -e ../antsibull-core
+pip install -e '.[dev]' -e ../antsibull-changelog -e ../antsibull-core -e ../antsibull-docs-parser -e ../antsibull-docutils
 [...]
 nox
 ```

changelogs/fragments/623-changelog.yaml

@@ -0,0 +1,3 @@
+minor_changes:
+ - "Automatically generate collection deprecation and removal changelog fragments from ``collection-meta.yaml`` information (https://github.com/ansible-community/antsibull/pull/623)."
+ - "Antsibull now depends on antsibull-docs-parser 1.x.y (https://github.com/ansible-community/antsibull/pull/623)."

noxfile.py

@@ -46,6 +46,7 @@ def other_antsibull(
  args = (
  "antsibull-core",
  "antsibull-changelog",
+ "antsibull-docs-parser",
  "antsibull-docutils",
  "antsibull-fileutils",
  )

pyproject.toml

@@ -28,6 +28,7 @@ requires-python = ">=3.9"
 dependencies = [
  "antsibull-changelog >= 0.24.0",
  "antsibull-core >= 3.1.0, < 4.0.0",
+ "antsibull-docs-parser >= 1.1.0, < 2.0.0",
  "antsibull-fileutils >= 1.0.0, < 2.0.0",
  "asyncio-pool",
  "build",

src/antsibull/changelog.py

@@ -39,6 +39,10 @@
  RemovalInformation,
  RemovedRemovalInformation,
 )
+from antsibull_docs_parser.parser import Context as _AnsibleMarkupContext
+from antsibull_docs_parser.parser import Whitespace as _AnsibleMarkupWhitespace
+from antsibull_docs_parser.parser import parse as _parse_ansible_markup
+from antsibull_docs_parser.rst import to_rst_plain as _ansible_markup_to_rst
 from antsibull_fileutils.yaml import load_yaml_bytes
 from packaging.version import Version as PypiVer
 from semantic_version import Version as SemVer
@@ -499,6 +503,16 @@ def __init__(
  self.collection_metadata = collection_metadata
 
 
+def _markup_to_rst(markup: str) -> str:
+ return _ansible_markup_to_rst(
+ _parse_ansible_markup(
+ markup,
+ _AnsibleMarkupContext(),
+ whitespace=_AnsibleMarkupWhitespace.KEEP_SINGLE_NEWLINES,
+ )
+ )
+
+
 def _get_removal_entry( # noqa: C901, pylint:disable=too-many-branches
  collection: str,
  removal: RemovalInformation,
@@ -575,7 +589,7 @@ def _get_removal_entry( # noqa: C901, pylint:disable=too-many-branches
  " due to violations of the Ansible inclusion requirements."
  )
  if removal.reason_text:
- sentences.append(removal.reason_text)
+ sentences.append(_markup_to_rst(removal.reason_text))
  sentences.append(
  "See `the removal process for details on how this works and can be cancelled"
  " <https://docs.ansible.com/ansible/devel/community/collection_contributors/"
@@ -588,7 +602,7 @@ def _get_removal_entry( # noqa: C901, pylint:disable=too-many-branches
  f"The {collection} collection will be removed from Ansible {removal.major_version}."
  )
  if removal.reason_text:
- sentences.append(removal.reason_text)
+ sentences.append(_markup_to_rst(removal.reason_text))
  if removal.discussion:
  sentences.append(
  f"See `the removal discussion for details <{removal.discussion}>`__."
@@ -662,7 +676,7 @@ def _get_removed_entry( # noqa: C901, pylint:disable=too-many-branches
  " due to violations of the Ansible inclusion requirements."
  )
  if removal.reason_text:
- sentences.append(removal.reason_text)
+ sentences.append(_markup_to_rst(removal.reason_text))
  sentences.append(
  "See `Collections Removal Process for"
  " collections not satisfying the Collection requirements"
@@ -677,7 +691,7 @@ def _get_removed_entry( # noqa: C901, pylint:disable=too-many-branches
  f"The {collection} collection has been removed from Ansible {removal.version.major}."
  )
  if removal.reason_text:
- sentences.append(removal.reason_text)
+ sentences.append(_markup_to_rst(removal.reason_text))
  if removal.discussion:
  sentences.append(
  f"See `the removal discussion for details <{removal.discussion}>`__."