Skip to content

Clean up table of contents in release notes #27898

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
wants to merge 1 commit into from
Closed

Clean up table of contents in release notes #27898

wants to merge 1 commit into from

Conversation

dstansby
Copy link
Member

@dstansby dstansby commented Mar 9, 2024 •
edited
Loading

PR summary

This cleans up the table of contents in the release notes, by adding one page per major version. It also makes the release workflow a bit simpler, by removing the github_stats page, and only requiring a new github stats file to be added, instad of keeping the old github_stats.rst page up to date.

Here's a link to the doc build on this PR: https://output.circle-artifacts.com/output/job/5ff26df4-22c8-4e09-bf69-8953f8f0dee0/artifacts/0/doc/build/html/users/release_notes.html

With this PR there's now a nice section navigation on the release notes page:
Screenshot 2024-03-09 at 18 45 39

To make it easier to use this re-arrangement going forward, I've also cherry-picked two sets of GitHub stats that are not on main yet, but these should be handled by #27899.

PR checklist

@github-actions github-actions bot added Documentation: build building the docs Documentation: devdocs files in doc/devel Documentation: user guide files in galleries/users_explain or doc/users labels Mar 9, 2024
@dstansby dstansby marked this pull request as ready for review March 10, 2024 10:14
@timhoffm
Copy link
Member

I'm -0.5 on this. The small per-version pages add another level of indirection. Users need one extra click to get to actual content. Also in the old versions you could see from the top page which bugfix versions exist and whether they have any API changes. That's more obscured now as well.

@story645
Copy link
Member

story645 commented Mar 12, 2024 •
edited
Loading

What about something like Pandas where they use indents and ordering by version number to structure information? So like:

Version 3.8

What's new in Matplotlib 3.8.0 (Sept 13, 2023)

3.8.3

3.8.2

3.8.1

3.8.0

If we use subheadings, then that will show up in the on this page for finding the bugfix releases.

@timhoffm
Copy link
Member

I like the pandas one:

  • They have one page per release with a heading "What’s new in 2.2.1", so these show up int the left sidebar. The page has subheadings for the different topics.
  • They have sections "Version X.Y" on the overview page, which is a high-level grouping in the right sidebar.
  • They use 
    .. toctree::
  :maxdepth: 2

  v2.2.1
  v2.2.0
    so that you see the subtopics in the overview page and can directly jump there.

Not sure if we can mimic this without creating a single page per version with all related content. (But changing to a single page per version would also be an option (we could use rst includes if we still want API changes and and features in separate files for better managability.

@dstansby
Copy link
Member Author

Thanks for the feedback! Since it looks like a more ideal solution would be different enough to this one, I'll close this PR, but when I get round to it will try and put a new one together.

@dstansby dstansby closed this Mar 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
Documentation: build building the docs Documentation: devdocs files in doc/devel Documentation: user guide files in galleries/users_explain or doc/users
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@dstansby @timhoffm @story645