Allow collections to render changelog as part of their docsite

[felixfontein]

Fixes #31.

To do:

• [x] Add documentation.
• [x] Add proper error handling.
• [x] Make configuration more future-proof.
• [x] Discuss at DaWG meeting where to place changelog on collection index page.
• [x] Add tests.

[felixfontein]

You can see the result here: https://ansible-collections.github.io/community.dns/pr/192/index.html#changelog (belongs to https://github.com/ansible-collections/community.dns/pull/192).

[felixfontein]

This is now ready for review! (I will only mark the PR as that on GitHub once the DaWGs meeting was able to talk about this.)

[samccann]

Thanks for this! I like the current location of where you put the changelog.

In the DaWGs meeting I mentioned that the left-hand nav is quite busy in the demo page. I'm not sure if this would be the same in the full docsite or not, but figured I'd mention it. @briantist mentioned it might benefit from using 'squash heirarchy'.

[briantist]

In the DaWGs meeting I mentioned that the left-hand nav is quite busy in the demo page. I'm not sure if this would be the same in the full docsite or not, but figured I'd mention it. briantist mentioned it might benefit from using 'squash heirarchy'.

Sorry my wording may have been confusing. The preview shown here, and its "busy" left-hand navigation, is caused by using --squash-hierarchy, something we use sometimes for docs previews like this, where only a single collection is being rendered.

It won't look like that on the main docsite, or anywhere where the option is not explicitly used.

--squash-hierarchy is an existing option in antsibull-docs that isn't related to this changelog functionality.

[samccann]

ah gotcha. thanks for clarifying!

[felixfontein]

Now we have @oraNod who prefers the changelog at the bottom of the collection index page, and @samccann who likes the current location. @briantist what do you think? And are there other opinions on this? :)

[samccann]

I posted on the docs channel as well in case anyone else has an opinion.

[briantist]

I don't think I'm leaning too strongly in either direction. I have maybe a slight preference for its current location, but it doesn't matter that much. Mainly I wouldn't want it stuck somewhere in the middle, so near the top like it is now (just after communication), or all the way at the bottom, are decent options.

[samccann]

Same here. Not a hill I'm wiling to die on. Go with either option.

[leogallego]

My take:

As both the changelog and the plugins list can be quite long dependending on each collection:

As long as the changelog is not too long, and ideally if it only shows the "big changes/deprecation warning", I would prefer the middle, so you get a glimpe of changes just by scrolling through the doc before reaching the plugins.

If it might be too long, then I would move it to the bottom, to avoid disrupting the plugin scrolling (which is most likely the reason you went to the docs in the first place)

[felixfontein]

This is only about a link to the changelog. The changelog itself is on a separate page. So don't worry about its length :)

[leogallego]

This is only about a link to the changelog. The changelog itself is on a separate page. So don't worry about its length :)

Oh, if it's just a link, then middle works better in my opinion. Helps remind people (me) to click at it while scrolling :)

Edit: by the way, by middle I mean the Index position (3rd out of 5 in the example)

[felixfontein]

In that particular example, the changelog is already in the 'middle'; it comes after the collection information (description, communication) and before the extra documentation (if available) and plugin/module/role index.

[felixfontein]

Since most like the current location and there haven't been more opinions, I'm going to merge the current version. I'll wait some more days before creating a new release, so if compelling new opinions / insights come up we can still change it without breaking something that's released :-)

[felixfontein]

Thanks everyone for your reviews and opinions!