GenericMappingTools / GenericMappingTools/pygmt

Try alternative Sphinx themes for the PyGMT documentation?

Open
#4,745 1 comment 0 reactions 0 assignees View on GitHub
discussions
Dominant language
Python
Stars
874
Forks
255
Avg merge
1d 21h
Merged PRs (30d)
40

Description

The PyGMT documentation has used the [Sphinx RTD theme](https://github.com/readthedocs/sphinx_rtd_theme) since its first commit. It has worked well, and its relatively infrequent releases (xref: https://github.com/readthedocs/sphinx_rtd_theme/tags) can be viewed as a good thing (stable behavior and little maintenance burden) or a bad thing (missing documentation features).

It may be worth experimenting with alternative themes from the [Sphinx Themes gallery](https://sphinx-themes.org/). One popular option is the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/), which is used by [NumPy](https://numpy.org/doc/stable/), [pandas](https://pandas.pydata.org/docs/), [xarray](https://docs.xarray.dev/en/stable/), and other projects in the PyData ecosystem. It offers a more flexible layout, light/dark mode, and configurable navigation.

I'm not proposing that we replace the current theme. Instead, this issue invites anyone interested to try an alternative in a small proof-of-concept PR and share a documentation preview or screenshots. We can then discuss whether a theme change would be worthwhile.

Contributor guide

Open the contributing guide

Research direction

Start by locating the current Sphinx RTD theme configuration in the documentation setup and compare it with a candidate theme from the Sphinx Themes gallery, especially PyData Sphinx Theme. A proof-of-concept is done when a PR provides a documentation preview or screenshots and enough comparison for the project to discuss whether changing themes is worthwhile.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.