pydata/pydata-sphinx-theme

many users struggle with version switcher/banner handling

Open

#1,629 opened on Jan 4, 2024

View on GitHub
 (7 comments) (0 reactions) (0 assignees)Python (376 forks)github user discovery
good first issuekind: documentation

Repository metrics

Stars
 (766 stars)
PR merge metrics
 (Avg merge 1d 14h) (18 merged PRs in 30d)

Description

we use the release value and not the version value from conf.py to decide whether to show a version warning banner. We are assuming folks follow what is stated in the Sphinx docs for release:

If you don’t need the separation provided between version and release, just set them both to the same value.

the fact that folks keep stumbling around the version switcher and the warning banner suggests that either (1) what we're doing is too fragile/magic, or (2) we're not documenting it clearly enough.

Originally posted by @drammock in https://github.com/pydata/pydata-sphinx-theme/issues/1445#issuecomment-1877861639

Contributor guide

Research direction
Investigate the current logic that uses `release` instead of `version` from `conf.py` to decide version warning banner, and propose improvements to make it less fragile or better documented. Consider user feedback and common pitfalls.
Tech stack
python
Domain
documentation
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
PythonSphinx
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60