search

nedbat / scriv

Changelog management tool
https://scriv.readthedocs.io
Apache License 2.0
260 stars 29 forks source link

Create stable URLs to changelogs #46

Closed maxking closed 2 years ago

maxking commented 2 years ago

Currently, scriv will generate rst sections for each version like

0.13.0 — 2022-01-23
-------------------

^ for an example from Scriv's docs. The URL for this is https://scriv.readthedocs.io/en/latest/changelog.html#id1, which is auto-generated by sphinx. The next time a new version is added, #id1 will be assigned to the first section in the page, which will make the URL point to different version.

In order to keep the anchors/urls consistent, scriv could add a simple anchor above the section

.. _changelog-0.13.0:

0.13.0 — 2022-01-23
-------------------

Also, url for each section within a single version is also changing continuously on version updates, https://scriv.readthedocs.io/en/latest/changelog.html#added for example points to the latest version's 'Added' section. The latter sections just using #id<N>

This can perhaps be fixed by adding an anchor something like: 

.. _0.13.0-Added:

I realize that it is possible to do at least the former by updating the config_entry_title_template (although, it'd be nice if it was a part of the default template), but the latter requires some changes since it is added scriv.format_rst.RstTools.format_sections and doesn't currently have a template.

I can open a PR with an implementation if you are open to it.

nedbat commented 2 years ago

I like the idea of stable URLs to each version section. I haven't needed URLs within the sections, and that seems more involved, so would it be OK to skip that part?

maxking commented 2 years ago

Yeah, ofcourse. It isn't needed as much as for the section header itself. I've had frequent asks for stable section level urls from users. I have opened #47 for that.