[Doc]: Release docs include Next what's new pages

[dstansby]

Documentation Link

https://matplotlib.org/stable/users/next_whats_new.html

Problem

Ideally this page shouldn't be in the docs for releases.

Suggested improvement

No response

[ksunden]

I don't think it is a real problem, the page is not linked to from https://matplotlib.org/stable/users/release_notes.html

So while yes it exists, it only is accessible by actively going to the url. (Or I guess by version switching from devdocs, at which point I don't really see a practical difference between loading an empty page and a 404)

The exclusion of the link from the parent page is managed automatically by checking for the release mode tag at build time.

I'm of the opinion that adding a manual step back to the release docs generation is clearly the wrong path forward, and that the complexity of an automated solution here is likely worse than the problem.

[rcomer]

It's in the sidebar of https://matplotlib.org/stable/users/release_notes.html. Is there a way to exclude it from there? It wasn't there for v3.7.

[timhoffm]

The sidebar is empty since #27800. So that’s not an issue anymore.

[dstansby]

The sidebar on e.g., https://matplotlib.org/devdocs/users/prev_whats_new/whats_new_3.8.0.html isn't empty though, and that shows up with "Next what's new?" and "Next API changes" at the top of the sidebar:

[timhoffm]

Yes, but #27800 deactivates that sidebar and is milestoned for 3.9.

[dstansby]

As far as I can tell, it only deactivates it for one page, https://matplotlib.org/devdocs/users/release_notes.html, and not other pages, e.g., https://matplotlib.org/devdocs/users/prev_whats_new/whats_new_3.8.0.html. The sidebar is turning up on the previous link, which is a devdocs link.

[timhoffm]

Oh, I see. Then, #27800 should be extended to show blank sidebars as well for api/prev_api_changes/* and users/prev_whats_new/*, which are logical subpages of the release notes.

On a side note, the relation between the logical toc hierarchy and the file structure is not quite trivial 😢.

[dstansby]

I think being on the "What's new for 3.8" and being able to see the section navigation is useful though, for example to go to the API changes or GitHub statistics. Surely the right solution to this is find a way to exclude "Next what's new" and "Next API changes" from release builds?

[timhoffm]

I think being on the "What's new for 3.8" and being able to see the section navigation is useful though, for example to go to the API changes or GitHub statistics.

I agree in theory, but due to the somewhat convoluted structure the menu is rather unusable. Note that there is a mix of 3.8.0 and 3.8.1 topics and "Github statistics for 3.8.1" even appears twice:

So until someone tries to untangle our incongruent use of logical hierarchy (sections) and page hierarchy, this side bar is rubbish.