WIP: draft PR from europython packaging sprint

[maxwell-k]

Fix #8152

(Edited by @uranusjr to inter-link to the issue)

[McSinyx]

Hello there, I am curious if Sphinx 3.x would work.

[maxwell-k]

@McSinyx I am curious also, I will hopefully get a chance to find out - that will maybe happen on a separate PR.

This PR so far has just been me trying to understand the build process for the documentation and make sure I understand enough to work on #8152 .

I am going to close it for now, because there isn't really anything to merge. I will be back online in five or six hours time and hope to work on it further.

[maxwell-k]

There may be a simple solution, I need to investigate further. I am re-opening this PR so that I can see the generated documentation at https://pip--8620.org.readthedocs.build/en/8620/news/

[McSinyx]

This seems to be working! Could you please capitalize the first letter in the news file and edit towncrier config in pyproject.toml to make this change apply for future releases?

[maxwell-k]

My initial analysis suggests that sphinx doesn't add stable anchors to the heading for each release because each heading is a "number". If you look at the stable release notes you can see that 20.1.1 doesn't get a stable anchor but 20.1b1 does. An acceptable solution might be to make sure each heading includes at least one letter. To come up with a suggestion I checked how a few related projects approach this:

• Sphinx prefixes each release heading with the word "Release" (Sphinx is used to build the pip documentation)
• towncrier prefixes each release heading with the word "towncrier" (towncrier is used to manage news fragments)
• Twisted prefixes each release heading with the word "Twisted" (Twisted is the project that towncrier originated from)

This PR currently prefixes all of the existing headings with the word "pip". I still need to:

• confirm this approach
• investigate how towncrier will work with future releases
• make sure CI passes

[McSinyx]

I'd vote for using the project name in this case, if there's to be a poll 😄 Regarding the second point, you can edit

pip/pyproject.toml

Line 10 in c6936ad

title_format = "{version} ({project_date})"

and run towncrier --draft in the project's root directory to see the output for the upcoming release.

[pradyunsg]

@maxwell-k Thanks for the PR! I don't think this approach is the correct fix. Looking at the examples provided, all those pages have some #<name><number> anchors, which means they're also unstable anchors.

https://www.sphinx-doc.org/en/master/changes.html#id5
https://github.com/twisted/towncrier/blob/master/NEWS.rst#features-7
https://github.com/twisted/twisted/blob/trunk/NEWS.rst#bugfixes-2

I think you agree since you've closed the PR? 😉

[McSinyx]

We can name the label the sections using e.g.

.. _features-20-2:

However, for this to work, we'd need a prerelease of towncrier to support versiondata.version in the template.

[maxwell-k]

@pradyunsg I closed the PR because it isn't really ready to pull because I didn't finish it at the sprints. If I get more time I'll reopen it or start another one. I see value in addressing the linked issue.

Perhaps we need to clarify the requirement in the linked issue. As I understand it the value is in linking to the section of the change log that corresponds to a release - for example "see this link for details of the changes in pip 25.0". The requirement may in fact be more complicated. @dgelessus who reported the issue may be able to confirm.

If that is the requirement, then this approach will work, for example here are 3 stable anchors from the corresponding docs build for this PR:

• https://pip--8620.org.readthedocs.build/en/8620/news/#pip-20-1-1-2020-05-19
• https://pip--8620.org.readthedocs.build/en/8620/news/#pip-20-1-2020-04-28
• https://pip--8620.org.readthedocs.build/en/8620/news/#pip-20-1b1-2020-04-21

I think that means that I disagree with you. Do you think that these links are unstable? Do you think that the requirement is different to how I have outlined it?

I'm not sure why you linked to the particular headings or sub-sections that you linked to. There are stable anchors for sections on each of those pages. For example:

• https://www.sphinx-doc.org/en/master/changes.html#release-3-1-2-released-jul-05-2020
• https://github.com/twisted/towncrier/blob/master/NEWS.rst#towncrier-1510
• https://github.com/twisted/twisted/blob/trunk/NEWS.rst#twisted-2030-2020-03-13

The "subsections" of each release do not have stable anchors. I would like to see other examples of release notes with stable anchors for subsections if anyone has any please; https://virtualenv.pypa.io/en/latest/changelog.html#features-20-0-21 is the example from #8152 .

If we're looking for links to sections rather than subsections the approach here may work and I can try and finish the PR (mostly with more testing!). Thanks for your help.