Allow markdown?

[geerlingguy]

Feel free to close if out of scope (since this maybe has implications on the ansible distribution build process), but after a few minutes working with RST I really wish for the simplicity of markdown.

And the fact that most contributors to community collections might not have familiarity with RST but are used to markdown means that messages they add to changelog fragments would likely be in markdown (e.g. with single backticks for inline code and other markdown-specific formatting) and might not look correct in the generated RST changelog.

I would like to have an option for markdown, if possible. If not, 🤷 but I'd still like the option :D

[felixfontein]

Sorry, this won't be supported in the near future. The changelog infrastructure for Ansible (previously ACD) is based on reStructuredText, so we need the changelogs/changelog.yaml with RST entries.

I guess what we can do is allow to have fragments and/or the resulting human-readable text file in MarkDown by using some RST <-> MarkDown converter, so that the changelog.yaml file can still contain RST. If someone wants to work on this, I'm happy to accept PRs, but I don't think I want to implement that.

[briantist]

Totally fair not to want to implement it!

The place where I would use this is on non-Ansible projects that are not using RST at all; I would want to generate the whole changelog in MD.

It's not a big deal because the RST file mostly renders usably on GitHub as long as you don't use most of the RST features (which generally these changelog entries don't).

Just offering a potential motivation for anyone who might be looking to contribute this.

[felixfontein]

I guess it would be possible to allow to change the markup format in changelogs/config.yaml so that every single string in the generated output, the changelog fragments, and changelogs/changelog.yaml is of the same markup type. That would be feasible.

What I'm a bit scared of is that some collections might decide "oh, now that we can, let's do our changelog in MarkDown instead of RST", and suddenly we cannot build a unified changelog for Ansible anymore.

[ephracis]

My use case for this is for custom collections built on prem and published to Private Automation Hub which only supports displaying markdown files in the GUI.

Being able to generate markdown files for our collections would allow users to read the change log where they browse and search for collections: PAH!

[felixfontein]

Right now it's possible to generate output both as MarkDown and RST, but the input still has to be RST. I'm using docutils with a MarkDown renderer (https://github.com/ansible-community/antsibull-changelog/blob/main/src/antsibull_changelog/rendering/markdown.py) to handle conversion from RST (or anything else that docutils can parse) to MD.

For supporting MD input, we'd need a RST renderer for docutils. There seems to be some code for that (https://github.com/sphinx-contrib/restbuilder/blob/master/sphinxcontrib/writers/rst.py), but it does depend on Sphinx, which is a dependency I'd rather not pull in. A basic RST writer shouldn't be that hard to create, so I guess this is definitely doable.