Skip to content

DOC: numpy. 2.0 documentation shows red in the version pulldown #27248

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

Open
mattip opened this issue Aug 19, 2024 · 9 comments
Open

DOC: numpy. 2.0 documentation shows red in the version pulldown #27248

mattip opened this issue Aug 19, 2024 · 9 comments

Comments

@mattip
Copy link
Member

mattip commented Aug 19, 2024

Issue with current documentation:

I uploaded 2.1 documentation. Now the version pulldown in the 2.0 documentation is showing red for 2.0. This is coming from #26125 (hi @melissawm) which un-commented the relevant css

Idea or request for content:

I don't understand

  • why NumPy has that stanza? In the PR it was meant to give some color to the version dropdown, but it doesn't seem to be working.
  • where the value for data-active-version-name comes from?
@mattip
Copy link
Member Author

mattip commented Aug 20, 2024

The pulldown button has this html for the 2.0 documentation

<button id="pst-version-switcher-button-2" type="button" \
   class="version-switcher__button btn btn-sm navbar-btn dropdown-toggle" 
   data-bs-toggle="dropdown" aria-haspopup="listbox" \
   aria-controls="pst-version-switcher-list-2" \
   aria-label="Version switcher list" \
   data-active-version-name="2.0" \
   data-active-version="2.0"> \
2.0 \
</button>

We have this CSS styling in numpy.css

.version-switcher__button[data-active-version-name*="devdocs"] {
  background-color: var(--pst-color-warning);
  border-color: var(--pst-color-warning);
  opacity: 0.9;
}

.version-switcher__button:not([data-active-version-name*="stable"])\
:not([data-active-version-name*="dev"])\
:not([data-active-version-name*="pull"]) {
  background-color: var(--pst-color-danger);
  border-color: var(--pst-color-danger);
  opacity: 0.9;
}

The theme documentation mentions the top CSS stanza, but not the second one. I don't know why #26125 enabled that stanza. It was applied to the 2.0 documentation but not activated due to the logic, but now that the 2.0 documentation is no longer "stable" the styling is activated. I submitted numpy/doc#27 to comment it out (waiting for review), but still do not understand what the motivation for making a version red. @tupui I think this was added in #21451?

Another point, the devdoc button has this html:

<button id="pst-version-switcher-button-2" type="button" \
   class="version-switcher__button btn btn-sm dropdown-toggle" \
   data-bs-toggle="dropdown" aria-haspopup="listbox" \
   aria-controls="pst-version-switcher-list-2" \
   aria-label="Version switcher list" \
   data-active-version-name="dev" \
   data-active-version="devdocs">
dev
</button>

So the CSS attribute does not match the first selector. I think that is due to the versions.json in numpy/doc which somehow gets converted to the data-active attributes, so the selector should be data-active-version-name*="dev":

[
    {
        "name": "dev",
        "version": "devdocs",
        "url": "https://numpy.org/devdocs/"
    },
    {
        "name": "2.1 (stable)",
        "version": "2.1",
        "url": "https://numpy.org/doc/stable/",
        "preferred": true
    },
    {
        "name": "2.0",
        "version": "2.0",
        "url": "https://numpy.org/doc/2.0/"
    },
...

@mattip
Copy link
Member Author

mattip commented Aug 20, 2024

Rather than fix the css selectors, another option would be to delete them and not attempt to colrize the button. We do have the header This is documentation for an unstable development version., so maybe that is sufficient?

@tupui
Copy link
Contributor

tupui commented Aug 20, 2024

do not understand what the motivation for making a version red. @tupui I think this was added in #21451

At the time there was no styling around the button and we wanted to give a visual indication to readers. The colours were chosen to be accessible (from a Nature paper IIRC).

@mattip
Copy link
Member Author

mattip commented Aug 20, 2024

a visual indication to readers

What is the special significance of this combinations that justifies coloring the button red for older versions?

not([data-active-version-name*="stable"])\
:not([data-active-version-name*="dev"])\
:not([data-active-version-name*="pull"])

@tupui
Copy link
Contributor

tupui commented Aug 20, 2024

This is debatable of course. It's just to incentivize more people to use latest always know if what they are looking at is the latest version of the doc. Some blogs or tutorials link to a specific version and people could not realize that something is deprecated/legacy.

@melissawm
Copy link
Member

Just a note that it should also be possible to use the version warning for old versions using https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/announcements.html#version-warning-banners (I'm not sure why it seems that was disabled for the 2.0 docs)

This is an example of how it shows (very similar to the warning for the dev version: https://pydata-sphinx-theme.readthedocs.io/en/v0.14.4/user_guide/announcements.html)

@mattip
Copy link
Member Author

mattip commented Aug 21, 2024

I'm not sure why it seems that was disabled for the 2.0 docs

Enabling/disabling the warning is not part of the documentation build instructions. What must be done to enable the warning?

In the mean time, until we resolve whether we want the 2.0 docs to be red, I merged numpy/doc#27 to disable the red styling.

@melissawm
Copy link
Member

I see that the option is enabled in our conf.py:

"show_version_warning_banner": True,
so I'm not immediately sure what the problem is. I can investigate later.

@timhoffm
Copy link
Contributor

timhoffm commented Jun 7, 2025

Note: numpy/doc#27 undid the coloring for the 2.0 docs. But the setting is included in the 2.1 and 2.2 docs.

2.1 is already red, and 2.2 will be once the 2.3 docs are up.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy