Render changelogs in docsite build

[felixfontein]

Inspired by ansible-collections/community.hashi_vault#299

There are a couple of things to discuss/decide:

1. Should this be done for every collection that has a changelog in the correct format, or only for collections who opt-in?

2. Should it use changelogs/changelog.yaml as the source of truth, or some rendered CHANGELOG.rst file? The trouble with the former (which I would prefer) is that antsibull-docs then needs to depend on antsibull-changelog in some form, which potentially leads back to the trouble of "updating antsibull-docs forces an update of antsibull-changelog" in ansible-core's test containers (antsibull-docs is only needed in the ansible-core default test container, while antsibull-changelog is included in all default test containers and thus updates to it are potentially user noticeable).

[mariolenz]

I think a changelog is an important part of the documentation, so I tend to have have it in docsite for all collections that have one in the correct format. This way, all users would benefit from having the changelog alongside the module documentation without the collection maintainers having to do something.

But I could also live with opt-in.

[briantist]

1. I would prefer that all collections which have one in the proper format have it in the docs, unless they opt-out of it.

I had used the "opt-in" language before, but for me this was more about letting collections use a different method publishing a changelog if they wish. But the "if they have [one] in the proper format" covers that well enough. I suppose we could allow an opt-out just in case they have one in the right format, but for some reason don't want it?

I especially like that having it "default on" (opt-out) means that most collections in the ansible package, if not all, and most collections in general that use the antsibull tools, will have the changelog viewable in docs, with no additional action needed.

I could also live with opt-in, but it can be hard to bring 100+ collections into changes like that, so adoption might be less.

---

2. I agree that using the YAML version as the source of truth sounds better. But the dependency thing sounds tricky.

What I might suggest then is starting out by using a rendered changelog for this feature. I also like the idea of being able to configure the path to the changelog, while it can default to <root>/CHANGELOG.rst. That would actually add a little flexibility for anyone who either renders a changelog with a different process (as long as it's RST in the end), no matter the name or location.

Using rendered also allows for a possibility of the rendered file being edited though I think that will be rare in the antsibull workflow since changes would be overwritten.

As a optional follow-up feature, if the dependency issues could be worked out, a YAML-based form could be introduced. If so, this could become the default mode (when nothing is configured), though for some of the reasons above, I think having an option to point to a rendered file is still good.

[briantist]

One additional thing we might like to consider, is customizing the title/heading of the page, at least in the TOC.

The current way I'm doing it with extra-docs, does not seem to support that. I'd rather not have the collection name repeated as it is now (community.hashi_vault Release Notes) but it's not the end of the world.

Give that the extra-docs.yml uses the term toctree, I looked at the docs and saw the form All about strings <strings>, however it didn't work in the YAML.

Anyway this is quite minor.

[felixfontein]

I decided not to allow foo <bar> directly, but provide an extended form (dict instead of string entry) which allows to specify that reference in parts. See #45 for the implementation. What do you think?

[felixfontein]

#134 adds support for a config file docs/docsite/config.yml inside collections, that could be used to configure whether changelogs are rendered or not.

[felixfontein]

2. Should it use changelogs/changelog.yaml as the source of truth, or some rendered CHANGELOG.rst file? The trouble with the former (which I would prefer) is that antsibull-docs then needs to depend on antsibull-changelog in some form, which potentially leads back to the trouble of "updating antsibull-docs forces an update of antsibull-changelog" in ansible-core's test containers (antsibull-docs is only needed in the ansible-core default test container, while antsibull-changelog is included in all default test containers and thus updates to it are potentially user noticeable).

This is no longer a problem BTW, since ansible/ansible-documentation was split off from ansible/ansible. So there's nothing stopping us from starting to depend on antsibull-changelog and implement 2 (which I prefer over 1).

[briantist]

very nice! I suppose using the yaml file also opens up new opportunities, like having a separate page for each version under the changelog top level tree, instead of as a single page (just as an example, I probably prefer a single page with headings myself).

[felixfontein]

I've started implementing this in #267.