Skip to content

DOC restructure changelog (in particular for switching to pydata-sphinx-theme) #28255

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.

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

Merged
merged 7 commits into from
Jan 25, 2024

Conversation

Charlie-XIAO
Copy link
Contributor

@Charlie-XIAO Charlie-XIAO commented Jan 25, 2024

Not sure if this can be directly put into main or I should target the new_web_theme branch.

This PR refactors the changelogs a bit. In particular, it avoids multiple top-level headings in one file, which should not have happened and is assumed by pydata-sphinx-theme when designing its heading styles. Also in this way the toctree will not show for instance 1.3.2, 1.3.1, 1.3.0, ..., but instead show only 1.3 which I think is desired.

Previous Current
image image
The micro versions are all shown because they are all top-level headings. I do not see a simple way to avoid this in sphinx: using :titlesonly: or :maxdepth: 1 would not work. We have top-level headings as minor version only. This may not look like much of an improvement with the current theme, but since pydata-sphinx-theme has the left sidebar that shows the global toctree, this change would make the navigation much simpler.
image image
There are multiple top-level headings for a single page. This is not a problem with the current theme but pydata-sphinx-theme assumes one top-level heading per page when designing its heading styles, so this would become an issue. There is only one top-level heading. Consequently the toggle menu in the current theme may provide less information, but this is not a problem for pydata-sphinx-theme since it has full pagetoc in the secondary sidebar.

Other changes

Since we have a single top-level heading now, I moved some "global" information (i.e., not specific to some micro version) from under the first micro version (e.g. 1.3.0) to under the top-level heading (e.g. 1.3). These include: the changelog legend, the link to the release highlight example, and the contributor list. Also note that the titles of the changelog legend and the contributor list are made into .. rubric:: to avoid them from appearing in the toctree. Rubrics in the current theme may not look outstanding enough, but with pydata-sphinx-theme they definitely look good.

Copy link

github-actions bot commented Jan 25, 2024

✔️ Linting Passed

All linting checks passed. Your pull request is in excellent shape! ☀️

Generated for commit: ab6c5f2. Link to the linter CI: here

@Charlie-XIAO Charlie-XIAO marked this pull request as ready for review January 25, 2024 07:33
Copy link
Member

@adrinjalali adrinjalali left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Targeting main is fine for this I'd say.

@Charlie-XIAO
Copy link
Contributor Author

Oh by the way, if this PR is merged can maintainers kindly sync new_web_theme with main? Thank you very much.

Copy link
Member

@glemaitre glemaitre left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just spotted a typo

@glemaitre glemaitre merged commit 72169ff into scikit-learn:main Jan 25, 2024
@glemaitre
Copy link
Member

Thanks @Charlie-XIAO

@Charlie-XIAO Charlie-XIAO deleted the changelog-refactor branch January 25, 2024 14:39
@adrinjalali
Copy link
Member

@Charlie-XIAO the new_web_theme branch is updated.

@Charlie-XIAO
Copy link
Contributor Author

Thanks @adrinjalali!

glemaitre added a commit to glemaitre/scikit-learn that referenced this pull request Feb 10, 2024
…nx-theme) (scikit-learn#28255)

Co-authored-by: Guillaume Lemaitre <g.lemaitre58@gmail.com>
glemaitre added a commit to glemaitre/scikit-learn that referenced this pull request Feb 13, 2024
…nx-theme) (scikit-learn#28255)

Co-authored-by: Guillaume Lemaitre <g.lemaitre58@gmail.com>
glemaitre added a commit that referenced this pull request Feb 13, 2024
…nx-theme) (#28255)

Co-authored-by: Guillaume Lemaitre <g.lemaitre58@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants