MAINT: Clean up whats_new and doc versions #11888

larsoner · 2023-08-15T20:09:56Z

Closes MAINT: Archive old doc versions #11885
Closes Version menu is getting too long #10932
Closes ENH: Split whats_new #10789

Refactor whats_new to show latest changes and link to all others
Refactor rst_prolog so we don't need to .. include:: links.inc and .. currentmodule:: mne all over the place
Add links to old doc version archives
Streamline links.inc to be much shorter and remove a lot of stuff we don't use (didn't check everything but checked some stuff at least)

@drammock let me know what you think. @sappelhoff also feel free to look since you had a preference for the long, continuous whats_new.html in #10789 . Will post CircleCI links once they render.

WIP until approved, then I'll:

revert the link to the versions.json from this branch
merge
remove 0.11 through 0.20 folders and versions_temp.json from mne-tools.github.io
update release Wiki with new instructions

* upstream/main: MAINT: Post-release deprecations, updates [circle deploy] (mne-tools#11887)

larsoner · 2023-08-16T00:08:00Z

This almost works:

But it links to https://mne.tools/dev/old_versions.htmlindex.html (note the added index.html). @drammock in theory it would be nice if pydata-sphinx-theme had some logic to say whether or not to add this. But in the meantime it's easy enough for me to move this to a doc/old_versions/index.rst and link to dev/old_versions/ as the URL for the older ... one.

larsoner · 2023-08-16T14:59:25Z

Note that I didn't update mne.tools/versions_temp.json to point to the right place so the older... link in the rendered HTML will not work, but it will once I revert the change in conf.py in this PR and we merge it. So this is ready for review/merge from my end!

doc/changes/devel.rst.template

doc/conf.py

doc/old_versions/index.rst

tutorials/preprocessing/40_artifact_correction_ica.py

drammock · 2023-08-16T15:24:28Z

doc/whats_new.rst

[nitpick]: making this into a "landing page" makes the page content 100% redundant with what's in the sidebar TOC. For mobile / small screens that's OK (arguably good?) but for big screens it looks odd to me. No action necessary unless it also bothers you and you have an idea how to fix it.

[more serious concern]: how will this page look on stable vs dev? I'm guessing that at release time the entry for changes/devel.rst gets altered to changes/v1.6.rst or similar, and then a new entry gets inserted for devel after the release is cut. Is that right? If so, has the releases Wiki been updated accordingly?

For mobile / small screens that's OK (arguably good?) but for big screens it looks odd to me. No action necessary unless it also bothers you and you have an idea how to fix it.

Yes I don't like it either but I think we can improve it later. Ideally pydata-sphinx-theme would allow per-page config of which sidebars to show / how to configure them. I guess we could probably do it already with themes since we do it with the homepage / index.html... but I think we can do it as a follow-up PR.

[more serious concern]: how will this page look on stable vs dev? I'm guessing that at release time the entry for changes/devel.rst gets altered to changes/v1.6.rst or similar, and then a new entry gets inserted for devel after the release is cut. Is that right?

Yes. So stable/ will not have the dev changes -- the topmost link will be to the X.Y release, which seems correct to me.

If so, has the releases Wiki been updated accordingly?

No I'll do that stuff after we merge, I'll add it to the TODO list at the top.

drammock · 2023-08-16T15:34:31Z

But it links to https://mne.tools/dev/old_versions.htmlindex.html (note the added index.html). @drammock in theory it would be nice if pydata-sphinx-theme had some logic to say whether or not to add this. But in the meantime it's easy enough for me to move this to a doc/old_versions/index.rst and link to dev/old_versions/ as the URL for the older ... one.

ouch that is not pretty. There are some changes to version switcher JSON in the dev version of the theme, so there's a chance it's already fixed but I'd have to check. For now please do switch so that it lives mne.tools/dev/old_versions/index.html

Relatedly, do we need to specify a numeric version for "older..."? I think it might work to just say the version is "old" (but again, maybe only with dev version of theme).

FYI I'm trying to get a new version of the theme released soon so feel free to just get it working and don't worry about testing against dev version of theme; I'll be doing that soon enough anyway.

Co-authored-by: Daniel McCloy <dan@mccloy.info>

larsoner · 2023-08-16T15:57:15Z

For now please do switch so that it lives mne.tools/dev/old_versions/index.html

Done!

Relatedly, do we need to specify a numeric version for "older..."? I think it might work to just say the version is "old" (but again, maybe only with dev version of theme).

I actually kind of like the idea of changing it to ≤ 0.20 ..., it's more explicit. I'll make that change

* upstream/main: Refactor test_epochs.py::test_split_saving (2 out of 2) (mne-tools#11884) Cross-figure event passing system (mne-tools#11685)

larsoner · 2023-08-16T20:15:06Z

Comments addressed and I wanted to get the mne-tools.github.io archiving done to hopefully speed up deployments (one timed out recently 😱 ) so I self-merged, happy to continue tweaking in follow-up PRs (or review from others).

sappelhoff · 2023-08-17T08:18:06Z

I get this for all versions except dev:

sappelhoff · 2023-08-17T08:22:32Z

And I'm a bit confused by the fact that version 1.3.1 is shown in the new changelog (notice the patch version increment):

Whereas all other options are without patch increments (even if such versions were released, see: https://github.com/mne-tools/mne-python/releases).

Other than that, and the comment about the error 404 above, I am happy with the changes here. thanks a lot @larsoner!

larsoner · 2023-08-17T12:04:27Z

I get this for all versions except dev:

The version dropdown it works for me (on dev and stable):

https://mne.tools/0.21/index.html

As does the whats_new:

https://mne.tools/dev/changes/v0.20.html

But it does look like there are corner cases:

If you are on a very old version like https://mne.tools/0.21/index.html and try to get to 0.11 it does 404
If you are on a page like https://mne.tools/dev/changes/v0.20.html and then try to nav to an older version, you get a URL like https://mne.tools/0.24/changes/v0.20.html that didn't exist back then.

The first one we can fix with trivial redirect index.htmls to the old_versions page, I'll do that manually in mne-tools.github.io now.

The second one is hopefully low impact since I think if people want docs like 0.22 they'll go there first from the landing index.html rather than trying to go from a nested page like changes/v0.20.html. But it's actually a problem in main even before this PR, so I opened #11893

sappelhoff · 2023-08-17T12:34:41Z

Okay, works for me as well now -- thanks for the explanations.

However what about this odd-one-out item?

And I'm a bit confused by the fact that version 1.3.1 is shown in the new changelog (notice the patch version increment)

In my opinion either:

this should be 1.3.0
all other "patch releases" should be documented in the changelog (both heading and content) as well (e.g., 1.4.0 should actually be 1.4.2)

larsoner · 2023-08-17T13:23:55Z

Indeed that should not be in the changelog I think. The point releases pretty much always contain redundant changes with the next major release...

larsoner · 2023-08-17T13:25:27Z

... snuck 1.3.1 cleanup into #11890 since that's marked for merge-when-green

* upstream/main: [pre-commit.ci] pre-commit autoupdate (mne-tools#11911) [BUG, MRG] Remove check on `mne.viz.Brain.add_volume_labels` (mne-tools#11889) Small splits fix (mne-tools#11905) adds niseq package to "Related software" (mne-tools#11909) Minor fixes for ERDS maps example (mne-tools#11904) FIX: Fix pyvista rendering (mne-tools#11896) BUG: Fix epoch splits naming (mne-tools#11876) ENH: Use section-title for HTML anchors in Report (mne-tools#11890) CI: Deploy [circle deploy] MAINT: Clean up whats_new and doc versions (mne-tools#11888) Refactor test_epochs.py::test_split_saving (2 out of 2) (mne-tools#11884) Cross-figure event passing system (mne-tools#11685) MAINT: Post-release deprecations, updates [circle deploy] (mne-tools#11887) MAINT: Release 1.5.0 (mne-tools#11886) [pre-commit.ci] pre-commit autoupdate (mne-tools#11883) Refactor test_epochs.py::test_split_saving (1 out of 2) (mne-tools#11880) FIX: Missing Saccade information in Eyelink File (mne-tools#11877) Improve drawing of annotations with matplotlib (mne-tools#11855) MAINT: Work around NumPy deprecation (mne-tools#11878)

Co-authored-by: Daniel McCloy <dan@mccloy.info>

larsoner added 2 commits August 15, 2023 16:09

MAINT: Clean up whats_new and doc versions [skip azp] [skip actions]

9cd1892

FIX: Labeling [skip azp] [skip actions]

5c814bd

larsoner force-pushed the versions branch from dff1ee6 to 5c814bd Compare August 15, 2023 22:38

larsoner added 2 commits August 15, 2023 19:45

Merge remote-tracking branch 'upstream/main' into versions

f8535a3

* upstream/main: MAINT: Post-release deprecations, updates [circle deploy] (mne-tools#11887)

TST: Just CircleCI [skip azp] [skip actions]

ff0150f

FIX: Link [skip azp] [skip actions]

eb1635b

drammock reviewed Aug 16, 2023

View reviewed changes

Update tutorials/preprocessing/40_artifact_correction_ica.py [ci skip]

56ebb79

Co-authored-by: Daniel McCloy <dan@mccloy.info>

larsoner added 5 commits August 16, 2023 12:02

FIX: Links [skip azp] [skip actions]

13e4ffa

FIX: Links [skip azp] [skip actions]

6d04eec

FIX: Links [skip azp] [skip actions]

ca8358e

FIX: Links [skip azp] [skip actions]

47d1d8c

Merge remote-tracking branch 'upstream/main' into versions

c7cc8e2

* upstream/main: Refactor test_epochs.py::test_split_saving (2 out of 2) (mne-tools#11884) Cross-figure event passing system (mne-tools#11685)

larsoner merged commit 921e027 into mne-tools:main Aug 16, 2023

larsoner deleted the versions branch August 16, 2023 20:09

sappelhoff mentioned this pull request Aug 17, 2023

ENH: Use section-title for HTML anchors in Report #11890

Merged

snwnde pushed a commit to snwnde/mne-python that referenced this pull request Mar 20, 2024

MAINT: Clean up whats_new and doc versions (mne-tools#11888)

74ae269

Co-authored-by: Daniel McCloy <dan@mccloy.info>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MAINT: Clean up whats_new and doc versions #11888

MAINT: Clean up whats_new and doc versions #11888

larsoner commented Aug 15, 2023 •

edited

Loading

larsoner commented Aug 16, 2023

larsoner commented Aug 16, 2023

drammock Aug 16, 2023

larsoner Aug 16, 2023

drammock commented Aug 16, 2023

larsoner commented Aug 16, 2023

larsoner commented Aug 16, 2023

sappelhoff commented Aug 17, 2023

sappelhoff commented Aug 17, 2023

larsoner commented Aug 17, 2023

sappelhoff commented Aug 17, 2023

larsoner commented Aug 17, 2023

larsoner commented Aug 17, 2023

MAINT: Clean up whats_new and doc versions #11888

MAINT: Clean up whats_new and doc versions #11888

Conversation

larsoner commented Aug 15, 2023 • edited Loading

larsoner commented Aug 16, 2023

larsoner commented Aug 16, 2023

drammock Aug 16, 2023

Choose a reason for hiding this comment

larsoner Aug 16, 2023

Choose a reason for hiding this comment

drammock commented Aug 16, 2023

larsoner commented Aug 16, 2023

larsoner commented Aug 16, 2023

sappelhoff commented Aug 17, 2023

sappelhoff commented Aug 17, 2023

larsoner commented Aug 17, 2023

sappelhoff commented Aug 17, 2023

larsoner commented Aug 17, 2023

larsoner commented Aug 17, 2023

larsoner commented Aug 15, 2023 •

edited

Loading