Warning alert:Documentation Syntax Error: cannot parse plugin documention.

Get Help
,
1

Hi Everyone,

ibm.storage_virtualize collection is successfully uploaded to the Galaxy portal after passing all the required checks, including:

  • ansible-test sanity
  • ansible-test units
  • ansible-lint

None of these tests reported any issues.

However, after the collection is uploaded, a few modules display the following warning on Galaxy:

Warning: Documentation Syntax Error: cannot parse plugin documentation.

Screenshot 2026-07-01 at 3.38.28 PM
Screenshot 2026-07-01 at 3.38.28 PM2394×1586 234 KB

To investigate further, I generated the collection documentation locally using antsibull by following the official documentation:

The documentation is generated successfully, and the affected modules are parsed correctly without any errors. I have attached a screenshot of the local output as well.

Screenshot 2026-07-01 at 3.39.03 PM
Screenshot 2026-07-01 at 3.39.03 PM2900×1656 355 KB

At this point, I’m not sure what I’m missing. Since the collection passes all the standard tests and the documentation builds successfully locally, I’m wondering:

  • Is there an additional validation performed by Ansible Galaxy that isn’t covered by ansible-test or antsibull?
  • Has there been a recent change or update in Galaxy’s documentation parser?
  • Has anyone else encountered this issue, and if so, what was the cause?

Any suggestions or pointers would be greatly appreciated.

One more thing I noticed is that the same
“Documentation Syntax Error: cannot parse plugin documentation”
warning is also shown for all of the previous versions of the collection, not just the latest release.

This makes me think the issue may not be related to the recent changes in the collection itself. Could this be an issue with the Galaxy documentation parser or the Galaxy portal?

2

It’s a known bug in Galaxy, and has been there for some time (there was some discussion about htis a few weeks before I created the issue on Matrix): Docs formatting broken on Galaxy for all modules/plugins that use `M(...)` (and likely also `P(...)`) in markup · Issue #5586 · ansible/ansible-hub-ui · GitHub

3

Thank You @felixfontein ,
for confirming that the issue isn’t with the collection and is instead related to Galaxy. I’ll keep an eye on the GitHub issue you mentioned.