Wishlist: Add basic extension to aggregate change log pages

[amotl]

About

In order to evaluate alternative views for the release notes published at ¹, and maintained at ², we may want to bring in some ideas from ³, or different ones, which closer match this use case.

Details

A sensible thing to start with, would be to aggreate individual pages into "one page per release" views. /cc @proddata

Footnotes

1. https://crate.io/docs/crate/reference/en/latest/appendices/release-notes/ ↩

2. https://github.com/crate/crate/tree/master/docs/appendices/release-notes ↩

3. https://github.com/zerotired/manticore-ext/blob/master/src/zt/manticore/ext/changes.py ↩

[amotl]

Exercise I

Just using vanilla .. include:: directives to re-bundle pages does not work well.

• Allow including documents multiple times (using different section numbers) sphinx-doc/sphinx#10744 (comment)

Warning, treated as error:
../docs/appendices/release-notes/5.0.0.rst:139:Duplicate target name, cannot be used as a unique reference: "breaking changes".

[amotl]

Exercise II

Thoughts

At sphinx-doc/sphinx#10744 (comment), we discovered that the MyST include directive offers a heading-offset directive option, which can

offset all the heading levels [of the included page] by a positive integer number.

-- executablebooks/MyST-Parser#262 (comment)

Based on that, @felixvd suggested at sphinx-doc/sphinx#10744 (comment) to place each include under its own header, and using the heading-offset directive option as intended.

Attempt 1

In 5.x.x.rst, we said:

#############
Release 5.0.0
#############

.. include:: 5.0.0.rst

However, it does not work, because the included page includes reference anchors, and parsing them twice makes Sphinx croak.

Warning, treated as error:
/Users/amo/dev/crate/sources/crate/docs/appendices/release-notes/5.0.0.rst:5:duplicate label version_5.0.0, other instance in /Users/amo/dev/crate/sources/crate/docs/appendices/release-notes/5.0.0.rst

Attempt 2

Then, we tried to use MyST, as @felixvd suggested. In 5.x.x.md, we said:

# Release 5.0.0

```{include} 5.0.0.rst
:heading-offset: 1
```

Unfortunately, files written in MyST Markdown are apparently not able to include reStructuredText files properly, so the result looks like that. Maybe there are corresponding options to make this detail work, maybe not.

[amotl]

Attempt 3

Idea

Using the :start-line: option of the .. include:: directive could be a potential quick solution/workaround, in order to skip the reference and heading at the top of the included page.

.. include:: member.rst
    :start-line: 5

-- https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment

Outcome

It does not work well, because within each page, just using

See `Breaking Changes`_.

is actually the culprit here, which causes this warning.

Warning, treated as error:
../docs/appendices/release-notes/5.0.0.rst:136:Duplicate target name, cannot be used as a unique reference: "breaking changes".