Switch to pydata-sphinx-theme #3165

ashnair1 · 2025-12-02T08:03:48Z

Fixes #2006

Widely used across the scientific Python ecosystem. Major libraries using this theme include NumPy, Pandas, SciPy, GeoPandas, Xarray etc. pytorch_sphinx_theme2 inherits from this theme (link) as well.

adamjstewart

Looks decent, fixes many of our bugs. Quite different from our previous theme, so may take some getting used to. Hasn't had a new release in almost a year, so either very stable or unmaintained.

I think there are a few other things we'll like to customize, such as default pages for different tabs and the version selection menu, but we can do those if we decide this is the style we want.

If it's not too much work, it would be nice to see a few other alternatives that are either simple or widely used by the community.

docs/conf.py

adamjstewart · 2025-12-03T12:04:54Z

docs/conf.py

+    'navigation_depth': 4,
+    'navbar_align': 'left',
+    'header_links_before_dropdown': 6,
+    'icon_links': [


These are cool!

docs/conf.py

.readthedocs.yaml

pyproject.toml

ashnair1 · 2025-12-03T13:49:55Z

One note on the landing page (index). Currently it shows the docstring in torchgeo/__init__.py (left image) but I could show the README instead (right image)

adamjstewart

I'm leaning towards this theme because it matches the rest of the PyTorch ecosystem but is still maintained. A couple remaining questions:

Are we able to remove any of the files in docs/_static? These were CSS hacks designed to fix bugs in pytorch-sphinx-theme.
I'm curious if there's a way to get rid of the version switcher in the bottom right corner and add one to the top menu bar like pytorch2-sphinx-theme. It's possible this is also a cache issue on my side.

docs/conf.py

adamjstewart · 2025-12-15T15:34:47Z

docs/conf.py

+# Sphinx 5.3+ required to allow section titles inside autodoc class docstrings
+# https://github.com/sphinx-doc/sphinx/pull/10887


I would also be okay with removing section headings from docstrings, I don't imagine it happens in very many places.

adamjstewart · 2025-12-15T15:36:06Z

.readthedocs.yaml

  tools:
-    # Sphinx 6.1 and older do not support Python 3.13+
-    python: '3.12'
+    python: '3.13'


Can test 3.14 now if you rebase

Needs #3203 to be merged

Technically that shouldn't matter, the pytest warning filters don't apply to sphinx anyway.

I tried switching to 3.14 earlier and the lightly warnings caused the RtD build to fail.

Hmm, that might be a problem. I don't know how to tell RtD to ignore that, #3203 shouldn't help.

You were right. Warnings are still raised. I'll proceed with building docs on 3.13 for now

ashnair1 · 2025-12-15T20:52:34Z

I'm leaning towards this theme because it matches the rest of the PyTorch ecosystem but is still maintained. A couple remaining questions:

Are we able to remove any of the files in docs/_static? These were CSS hacks designed to fix bugs in pytorch-sphinx-theme.

I'm curious if there's a way to get rid of the version switcher in the bottom right corner and add one to the top menu bar like pytorch2-sphinx-theme. It's possible this is also a cache issue on my side.

I have added the version switcher to the top of the navbar
I was able to remove badge-height.css and table-scroll.css without affecting the docs. notebook-prompt.css could be removed as well but I didn't go through with it as I think we don't want those line numbers. Below image shows how it would look. Left (current), Right (without notebook-prompt.css)

This reverts commit 0b8eb87.

ashnair1 · 2025-12-17T15:28:08Z

Note: Currently colors are based on the default pydata-sphinx-theme i.e. blue and purple. This can be overridden with a custom css. Can be done in a later PR

adamjstewart · 2025-12-17T15:46:42Z

Python 3.14 error is:

WARNING: Failed to get a method signature for torchgeo.datasets.GeoDataset.__annotate_func__: None is not a callable object

This looks like sphinx-doc/sphinx#13701. So Sphinx 9+ is required for Python 3.14+.

ashnair1 · 2025-12-17T15:54:00Z

Python 3.14 error is:
WARNING: Failed to get a method signature for torchgeo.datasets.GeoDataset.__annotate_func__: None is not a callable object
This looks like sphinx-doc/sphinx#13701. So Sphinx 9+ is required for Python 3.14+.

Only thing stopping us from supporting sphinx 9+ is myst-parser which currently doesn't support sphinx 9+ and is required to render the README in the documentation. Once executablebooks/MyST-Parser#1076 is merged that should be solved.

adamjstewart · 2025-12-17T16:02:52Z

Drop the README then 🙂

ashnair1 · 2025-12-19T19:05:26Z

Docs now work with Python 3.14. There is an issue with tutorials test though.

github-actions bot added documentation Improvements or additions to documentation dependencies Packaging and dependencies labels Dec 2, 2025

ashnair1 marked this pull request as ready for review December 2, 2025 19:15

ashnair1 requested a review from adamjstewart December 3, 2025 03:52

adamjstewart reviewed Dec 3, 2025

View reviewed changes

github-actions bot added the datasets Geospatial or benchmark datasets label Dec 3, 2025

ashnair1 force-pushed the docs-pydata branch 2 times, most recently from addb7b1 to 415f278 Compare December 3, 2025 13:38

ashnair1 force-pushed the docs-pydata branch from 415f278 to 1205f8d Compare December 3, 2025 19:58

ashnair1 mentioned this pull request Dec 7, 2025

Change documentation theme #2006

Open

adamjstewart reviewed Dec 15, 2025

View reviewed changes

ashnair1 force-pushed the docs-pydata branch 3 times, most recently from 89004f4 to 35b6ea0 Compare December 15, 2025 20:02

ashnair1 added 14 commits December 16, 2025 21:42

Initial commit

6eabaa2

flat list -> navigation tabs

7317935

Specify min version of sphinx for Python 3.13

ae78287

Ignore CRS warnings

64b0a40

Add missing index files

1fb3a48

Remove todo

a8a0a96

Stop ignoring sphinx updates

c210ff8

Remove docs/requirements.txt

e948fbd

Specify min version of pydata-sphinx-theme

c915c85

Set CRS default as None

b665aed

Add Slack invite link

5aa1ce3

Update min version of sphinx and pydata-sphinx-theme

8887b3d

Add myst-parser to display README as index page

167d258

Add switcher

2e6b558

ashnair1 added 6 commits December 16, 2025 21:42

Pin sphinx version

9fea59e

stable -> latest

ecba7d1

Test switcher

6e2da2d

Use Python 3.13

534dcef

Update switcher

f7fde65

Update

8c4dff8

ashnair1 force-pushed the docs-pydata branch from 8bbde1c to 0b8eb87 Compare December 16, 2025 17:43

ashnair1 added 2 commits December 16, 2025 21:43

Test Python 3.14

0b8eb87

Revert "Test Python 3.14"

866d22f

This reverts commit 0b8eb87.

ashnair1 added 2 commits December 17, 2025 20:27

Drop README

5026f83

Test Python 3.14

2a0098a

		# Sphinx 5.3+ required to allow section titles inside autodoc class docstrings
		# https://github.com/sphinx-doc/sphinx/pull/10887

Switch to pydata-sphinx-theme #3165

Are you sure you want to change the base?

Switch to pydata-sphinx-theme #3165

Uh oh!

Conversation

ashnair1 commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adamjstewart left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adamjstewart Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ashnair1 commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adamjstewart left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adamjstewart Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

adamjstewart Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

ashnair1 Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamjstewart Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

ashnair1 Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

adamjstewart Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

ashnair1 Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ashnair1 commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ashnair1 commented Dec 17, 2025

Uh oh!

adamjstewart commented Dec 17, 2025

Uh oh!

ashnair1 commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adamjstewart commented Dec 17, 2025

Uh oh!

ashnair1 commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ashnair1 commented Dec 2, 2025 •

edited

Loading

ashnair1 commented Dec 3, 2025 •

edited

Loading

ashnair1 Dec 16, 2025 •

edited

Loading

ashnair1 Dec 16, 2025 •

edited

Loading

ashnair1 commented Dec 15, 2025 •

edited

Loading

ashnair1 commented Dec 17, 2025 •

edited

Loading

ashnair1 commented Dec 19, 2025 •

edited

Loading