DOC: more modern sphinx theme

[jorisvandenbossche]

We currently use a slightly adapted version of the 'nature' theme (you can also see it in this list of built-in themes: http://www.sphinx-doc.org/en/stable/theming.html#builtin-themes).

I think this can use an update, for some reasons:

• a mobile friendly theme (more and more useful, and currently this completely fails on mobile)
• more powerful theme (allowing eg better nested structure of the docs, which could enable a reorganisation of the docs. Now we have a single flat table of contents on the left)
• refreshed look (but this is subjective of course :-))

(could go together with a refresh of the main website as well, but not necessarily I think)

http://www.writethedocs.org/guide/tools/sphinx-themes/

[TomAugspurger]

This would help out with #15539 (nbsphinx for notebook build), as the generated HTML tables inherit the not so nice table sytling

(other than that nbsphinx worked flawlessly. Pretty amazing).

[jorisvandenbossche]

@stijnvanhoey would like to do some work on this. I was personally thinking about creating a separate repo (eg 'pandas-dev/pandas-sphinx-theme'), just to not create more traffic on our main repo (about something not core pandas related). But that would then mean to eg use git submodule to include the sphinx theme here in our docs (what eg numpy does: https://github.com/numpy/numpy/tree/master/doc).
Any opinions on that?

cc @jreback @TomAugspurger

[jreback]

ok by me.

[TomAugspurger]

That seems fine.

[datapythonista]

I'm working on a proof of concept to see options to address this issue, a more clear home (not sure if there is an issue for it) and also #15632.

You can see what I've got so far here: http://datapythonista.github.io/docs/new-pandas-doc/home.html (still WIP, but gives an idea).

Code available here: https://github.com/datapythonista/pandas/tree/doc_home

[jorisvandenbossche]

Cool!

For the actual theme, I created https://github.com/pandas-dev/pandas-sphinx-theme a while ago (to have the discussion and design iterations there), which is set up to directly show the different options on gh-pages (the different branches) with a demo pandas documentation:

• current one (master): https://pandas-dev.github.io/pandas-sphinx-theme/
• an initial start on a bootstrap theme by @stijnvanhoey: https://pandas-dev.github.io/pandas-sphinx-theme/pr-bootstrap-theme/
• a comparison with readthedocs theme: https://pandas-dev.github.io/pandas-sphinx-theme/pr-readthedocs-theme/

I will give you rights to that repo as well so you can contribute there (the branches (for PRs) need to be on the repo and not fork for doctr to automatically build it)

[jorisvandenbossche]

So @stijnvanhoey did some work on that some time ago (we discussed some things offline), but Marc, let's not let that hold you back! (we're all busy people :-))
And also it seems you are starting of from the same theme, so that even makes it easier to contribute on it.

[datapythonista]

Cool, didn't see that there was a theme in a separate repo, thanks for the info and the access @jorisvandenbossche .

Seems like the theme and the styles are almost the same, happy to continue on what has been done.

What about the general idea of home page I built [1]? I'm surely biased, but IMO makes it easier to find the different pages, compared to the options in the navigation bar in the pandas-dev bootstrap home [2].

1. http://datapythonista.github.io/docs/new-pandas-doc/home.html
2. https://pandas-dev.github.io/pandas-sphinx-theme/pr-bootstrap-theme/index.html

[jorisvandenbossche]

(warning: long comment coming :-))

didn't see that there was a theme in a separate repo

That was also not yet advertised, so that is normal :-)

What about the general idea of home page I built [1]? I'm surely biased, but IMO makes it easier to find the different pages, compared to the options in the navigation bar in the pandas-dev bootstrap home [2].

It might serve a different purpose, eg the homepage of the documentation subsite vs the homepage of the general pandas site (which directly has links to subsets of the documentation in the top bar).
And that's already one of the aspects to discuss to what extent we want to integrate both.

Personally I like having both a top navigation bar and side navigation bar, because the pandas documentation is so huge that it IMO would benefit from multiple layers of navigation (the current sidebar is way too long and does not give a good overview). If you are on a specific page (eg http://datapythonista.github.io/docs/new-pandas-doc/options.html in your example), the question is still how to navigate from there to another page. Of course answer can there be to go back to the home page, and make there a new choice. But I think we should think about how exactly we want to have the top and side bar to make this navigation easier.
Anyway, both also don't exclude each other: you can have such a top bar but still have this overview page on the main doc landing page.

---

I think there are several (of course intertwined) issues to tackle:

1. New sphinx theme

As listed at the top of this issue: a new, fresh and mobile friendly sphinx theme.
And for me, one of the important goals of such a new theme should be that it is more powerful to allow a more advanced structure / navigation than the current theme with the single flat list on the left side (which is the part where it overlaps with the other issues 2 and 3).

• Do we write and maintain a custom one? (which can of course still largely be based on existing ones, like the bootstrap theme)
• Or would we actually be happy to, for example, simply go with the readthedocs theme? Which can easily be given a 'personal' touch (like http://dask.pydata.org/en/latest/docs.html or https://keras.io/)

2. Top-level reorganisation of the site / docs

Personally I think the long flat list of pages in the current navigation makes it very hard to quickly find something in that list (related issue for this: #6000).
For this aspect, I would go for some bigger "sections" like Getting Started, User Guide, Reference Guide, Community, Contributing, .. but that is of course completely up for discussion.

When we would go for such a more hierarchical structure, then the theme needs to support this.

• Do we only make such a subdivision for the documentation website (and think separately about re-working the main website), or do we integrate it at once with the main landing page?

  • Dask (http://dask.pydata.org/en/latest/) is an example with still a separate main landing page (although many of the top bar links point to doc subsections)
  • If we choose a new theme with some visual identity for the docs, it would be nice to at least visually align the main landing page as well (but they of course still be separate structures).

• How hierarchical do we want the structure to be?

  • Going from a quick grouping the pages under headers in eg the readthedocs theme, with as example the headers in the dask (http://dask.pydata.org/en/latest/docs.html#) or xarray (https://xarray.pydata.org/en/stable/) sidebars
  • to a very hierarchical example from the tensorflow docs (eg https://www.tensorflow.org/programmers_guide/datasets) with a two-level top bar, left side bar for different pages, and right sidebar for within page navigation
  • or something in between :-)

I see this issue nr 2 mainly as a reorganisation of the existing documentation pages, to get a relatively quick win in better navigation without rewriting the docs.

3. Restructuring individual documentation pages

Personally I think some / many of our documentation pages are too long and not that beginner-friendly (many user guide pages are more reference guides).
To use the example of the "Indexing and Selecting Data" page (which goes up to code block nr 350), I can imagine a structure where the main landing page for this part of the documentation gives a more general overview of the concepts of indexing and selecting data in pandas, properly referring to then several more in depth pages on the several topics related to indexing (using loc/iloc, the index object, multi-index, query, ...)

The "User Guide" could then be divided in some of those big topics as IO, Indexing, Reshaping, Merging/concatenating, Visualization, Working with time data, Working with Categorical data, .. (which would be for the most part a subset of the current pages), and the landing page for User Guide could give a nice overview of those topics.

This is however an even much bigger endeavour :-), so I would for now focus on the two issues above. But, in thinking about the navigation and the theme, it would be nice to at least have this use case in mind to make sure it would be possible.

[datapythonista]

Thanks a lot for organizing the discussion. I agree on everything you said.

About 1) the sphinx theme, my experience with the sphinx bootstrap theme is really good. Opened couple of issues, and seems like many people is actively maintaining the project. I'm sure if pandas needs some customization, they'll be happy to help with that. So I don't see any reason to maintain a separate theme at this point.

About 2) the site structure, I also think that having around 40 sections in the top level makes things very complicated to find. That was the discussion I wanted to have, on how I organized the different pages. I think the sections you propose are more or less the same than the ones I defined in my home, I guess that's the obvious division then. I also thought about whether it'd make sense to merge pandas.pydata.org with the documentation. I'm happy with both options.

About 3) changing and splitting pages, I think it'll help a lot to have 2) completed to see things clearer. For example, if we manage to have a section "Getting started", it'll be much easier to think on how this section can be structured, if any page should be splitted... than with the current structure where everything is mixed.

What would you think on the next roadmap:
a) decide which theme to use
b) replace nature with the new theme in master
c) discuss which main sections we want (Getting started, Reference...)
d) discuss how the navigation of the page should be (sidebars, toctree depth, previous/next links...)
e) replace the current home (index) with the new sections, and customize the theme with the desired navigation in master
f) keep refining the pages (splitting, merging, avoiding duplications...)

Personally, I think it's better to keep changing master step by step, than have a branch or a separate project for the whole thing.

[stijnvanhoey]

I do agree with @datapythonista about using (and contributing to) the bootstrap sphinx theme as the theme for Pandas instead of a separate theme. I see benefits for using readthedocs as well (cfr. how dask does this), but the top bar of the bootstrap theme is something nice to have some main headers/topics.

I do like the general overview of pages, but on the other hand I would make it more 'welcoming' for newcomers and combine it with a proper side and header menu in order to support continued navigation (cfr. what joris mentioned on having to go back to the home page).

I tried to make some 'mockup' like examples for a potential set of header items, which more ot less corresponds to the main items of Marc's example. Not yet implemented, but to have a visual starting point for the discussion. Most of it I do think is achievable from within the bootstrap theme itself...

1. An installation page with the pages relevant for installation:
   

2. The user guide (cfr. contents); this is actually the largest set of pages, which would need further split up of individual pages, etc.

(an important item here is to lower the barrier to update te docs (just a direct link)

3. API reference. Well, an API reference...

4. Contribute/development page

5. A community page. I do think this is an important one and needs to be engaging. I like the example of vispy.

6. News, which is the new releases changelog. Main issue now is that the page is HUGE and won't load, so we have to make this easier

@datapythonista how can we proceed with this discussion? I propose to add the svg to the pandas-dev/pandas-sphinx-theme repo and maybe discuss from there?

[datapythonista]

Thanks for the wireframes @stijnvanhoey, they really help understand better your ideas. I'm happy with what you propose. And I don't see a problem on having the home for the documentation you propose, and then a "index" with the structure of the home I created, if that adds value with the final layout.

If there is an agreement on using the bootstrap theme, I'm not sure if the pandas-sphinx-theme repo is useful more than to visualize the documentation, right? I mean, we won't have a pandas-sphinx-theme, and we would just add bootstrap-sphinx-theme to the dependencies, if I understand it correctly.

What would you think if we start by opening a PR to the pandas repo to replace nature by bootstrap with the minimum changes? Keeping the current structure, and without any additional menu or page. Once that is implemented, it should be easy to have new issues/PRs for each of the different things under discussion independently (navigation, home page, community page...).

[jorisvandenbossche]

The reasons that I thought the separate repo was a good idea was for the following reasons:

• in the idea that in the end it might become a custom theme (or theme based on an existing one but with customizations). This I cannot really judge to what extent we will need to customize or not.
  But note that we currently also have a custom theme (meaning, we have a theme directory in our docs that contains custom css and templates). It can still be an option to keep this in a separate repo even after the experimental phase, e.g. if we also use it for the pandas-website (although this might be more annoying than helpful in practice)
• in the idea that it would generate some discussion and iteration, and to off-load some of that traffic from the main pandas repo (there are already too many issues and PRs to follow here, and this is not really pandas functionality-related)
• It gives easier review of PRs because it is set up to provide a rendered version
• It gives an easier way of experimenting / iterating because a PR can be merged before the theme is in a usable state.

It's true that if we already agree on a way forward, it makes the separate repo less pressing. But, personally I think we can still experiment there first.
IMO we should not merge an initial version already in master (the "replace nature by bootstrap with minimal changes"), because this should not block a release (we don't know how long it will take to get something we are satisfied with) and I think we should directly have a good version (which doesn't mean it needs to be perfect!) when we use the new theme in a released version.
The organisation and the theme of the docs is also a form of user experience, people get used to navigate the docs. This is therefore not something we should change too often IMO.

(if I am making things too complicated, please argue so :-) )

[stijnvanhoey]

I agree with @datapythonista about the index on the first page, so let's integrate both ideas.

I do understand the arguments of @jorisvandenbossche, so I'm ok with doing it on the separate repo, but maybe we could take into account the roadmap as defined by @datapythonista and try to have an integration towards pandas repo itself on different stages (a/theme switch b/...)?

[datapythonista]

My main concern is working for too long with different copies of the documentation .rst files, the conf.py... as at some point it could become tricky to integrate that code back.

But as per @jorisvandenbossche comments I'm happy to discuss and experiment in the other repo until we have the theme customized and the navigation defined. Then we can see how much code our theme has, and whether it's better to keep it in a separate project. And we can see in which repo makes more sense
to work on refining, splitting... the individual pages.

[jreback]

just saw this: https://ofosos.org/2018/12/28/landing-page-template/

[datapythonista]

thanks, that's the same approach I'm already using in https://pandas-dev.github.io/pandas-sphinx-theme/pr-datapythonista_base/

[WillAyd]

Moving some discussion from core team mailing list back here. So I was able to build a copy locally with the sphinx_rtd_theme with some screenshots below. Here's my local branch where you can see the changes (rather minimal)

Compared to current nature theme the TOC on the left stays pinned which is nice when scrolling through larger pages. It also provides dropdown in the TOC (current theme requires you to physically click on level to expand sub-entries)

Maybe we can just use this for the time being? Doesn't exclude us from doing any of the aforementioned ones but this seems like a very easy drop-in replacement:

[jorisvandenbossche]

You can also see a live version here: https://pandas-dev.github.io/pandas-sphinx-theme/pr-readthedocs-theme/index.html (although that is with only a part of the docs, should update it for the new structure we have on master / latest release)

[jorisvandenbossche]

@WillAyd (and others) to come back on #25614 (using the readthedocs theme for our docs).

First, readthedocs (sphinx_rtd_theme) is a really nice documentation theme: it is much better than our current theme (looks better, better responsiveness, etc), it is well maintained, and it is used by other projects as well (so gives some familiarity to users).
So that are certainly important advantages for moving to the readthedocs theme.

But personally, I find the readthedocs theme mainly great for relatively simple documentation websites, where the single sidebar navigation (as we also have currently) is sufficient, but lacking for very complex documentation sites where you would like more "levels" of navigation (eg combine top navbar with sidebar).
That is one of the reasons we have been looking into eg a bootstrap based theme (by @stijnvanhoey and @datapythonista, see links above). Although there is some difficulty in getting sphinx' toctrees talk properly with more advanced theme navigation (see eg #23763 for Marc's experience).

Given this renewed activity on the theme (@WillAyd opening the PR), I wanted to do a final quick test on how feasible it would be to have a more advanced (in terms of navigation) theme based on bootstrap. Instead of basing it on https://github.com/ryan-roemer/sphinx-bootstrap-theme (which doesn't yet support bootstrap 4, and also does not fully allow this multi-level navigation out of the box), I basically copied the templates and styling from the bootstrap docs (https://getbootstrap.com/docs/4.3/getting-started/introduction/) and did some sphinx hacks to get it working.

The result can be seen here: https://pandas-dev.github.io/pandas-sphinx-theme/pr-bootstrap-docs-theme/user_guide/text.html

This should give the "idea" of what I would like to see for the pandas docs, but some notes:

• This is of course a straight copy of the styling of the bootstrap docs. We might want a different look (eg different colors), so don't look too much at that. Also, some sphinx specific constructs (eg the "note" or "warning" boxes) don't have yet custom styling (would need to copy some css from sphinx based projects for that)
• The idea is that it would highlight in the left and right sidebar (and also top navbar) where you are. This highlighting is currently still missing (amongst other things because sphinx uses "current" and bootstrap "active")
• The home page of the docs should of course be reworked to fit into this (and can use a rework anyhow :-))
• The IPython blocks are not executed (so you only see the input, not the output), just to speedup testing. But noting in case you would wonder.

But it should give some idea of what is possible with a theme based on this.
Of course, this is still more custom development (although based on an active developed framework, and we might be able to keep it close to their docs theme, to make it easier to port changes), and not simply using a existing theme (such as readthedocs). But personally, I think it can give a better documentation website for pandas.

[WillAyd]

I am not stuck on it but I still have a slight preference for readthedocs if only because it represents the least amount of work and maintenance and looks "good enough" in my opinion. I do think bootstrap could look better but I'm wary of having to customize things because none of us (I don't think) have extensive web dev experience and that can be rather tricky.

For example, the link you provided is already rather difficult to navigate from a mobile device when compared to the rtd theme. In a vacuum this probably isn't a big deal since I doubt that many people are reading pandas docs from a mobile device, but I think it speaks to time and effort I think customizing a theme could take to correctly support devices which isn't value add for us

In any case like I said it's a slight preference but not something I'm tied to. Certainly let's hear everyone else's opinions

[WillAyd]

Sure looks like that does have better support

[jorisvandenbossche]

For some other examples (next to https://getbootstrap.com/docs/4.3/getting-started/introduction/) that have a nice theme ("nice" in my opinion = allow good navigation for more complex docs + looks good):

• https://sourcethemes.com/academic/docs/
• https://squidfunk.github.io/mkdocs-material/

Both could also be used as a starting point (take there theme + adapt templates to work with sphinx). The "academic" one is also based on bootstrap, the "material" one based on Material Design.

[jorisvandenbossche]

Any others with an opinion about this (#15556 (comment)) ?

[jreback]

starting with an existing already done theme that provides the sophistication as outlined here: #15556 (comment) is +1 from me

[jorisvandenbossche]

I also updated the readthedocs version with the same subset of the current docs, for easier comparison:

• Current theme: https://pandas-dev.github.io/pandas-sphinx-theme/
• Readthedocs theme: https://pandas-dev.github.io/pandas-sphinx-theme/pr-readthedocs-theme/user_guide/text.html
• Bootstrap based theme (with splitted navigation): https://pandas-dev.github.io/pandas-sphinx-theme/pr-bootstrap-docs-theme/user_guide/text.html

[WillAyd]

@jorisvandenbossche what conf settings are you using? FWIW the RTD theme you have built is a little rougher for TOC navigation than what was shown in #26514 as you physically have to visit a topic on the left hand side to expand its navigation. Maybe worth trying out the conf settings in that PR to see if that improves (may apply to both themes)?

[jorisvandenbossche]

@WillAyd for now I only switched html_theme = "sphinx_rtd_theme", leaving all the rest intact (meaning the default settings of readthedocs I think.

I see that in that PR, you used in addition:

html_theme_options = {
    'collapse_navigation': False,
    'navigation_depth': 2,
}

However, if I do that, you don't get any navigation within a page any more (the left side bar then only goes up to the page for eg the user guide), which was what we temporally had with our current theme after the reorganisation, was reported in #25131 and fixed in #25134 to have again an additional level.

(for the collapse_navigation, I don't directly notice a difference locally when I set it to True or False, but I don't really understand your "you physically have to visit a topic on the left hand side to expand its navigation". That seems to be the case with eg the readthedocs docs as well https://sphinx-rtd-theme.readthedocs.io/)

---

For me, this also shows the problem I have with the combination of our docs and the readthedocs theme. Either you set the navigation_depth to 2, but then you don't have any navigation any more in our very long doc pages (#25131), or either you set it to a larger depth, but then once you expand this in eg the IO user guide page, the left sidebar gets so long that you don't see a lot of the navigation any more and you need to scroll inside the navigation. By splitting the navigation in eg a top bar and a left side bar, you can try to prevent this to a certain extent.

[datapythonista]

I agree with what has been said by both @WillAyd and @jorisvandenbossche

• The RTD theme is surely an improvement to what we have (better look, responsive...)
• It's designed for small docs, and not really for pandas doc needs

While not against changing the theme temporary to RTD, my preference is keep working towards the final version. I don't think the effort to change to the RTD theme is much less than changing to the bootstrap theme (that based on the research of @stijnvanhoey and myself is the best option).

A quick change will leave a lot of work pending, of course:

• Better navigation
• Customization of the theme (colors, logo...)
• A good home page
• Integrating the website (which with RTD doesn't seem reasonable)
• ...

But from my experience, it makes much more sense to work on it step by step in small PRs, as we did for the structure. And in that way, I'd change to the bootstrap theme, which goes into the right direction.

I think we don't have a release planned for some time now, right? If that's the case sounds like a good time to start the transition, and have something that looks more finished for the next release.

[datapythonista]

Btw, you can see the work done with the bootstrap theme here: https://pandas-dev.github.io/pandas-sphinx-theme/pr-datapythonista_base/index.html

In this last version I removed the navigation in the top bar (to test how it looks), but the idea is to have the main sections there.

[WillAyd]

"you physically have to visit a topic on the left hand side to expand its navigation".

What I mean by this is the difference between this screenshot:

And this screenshot:

Note that in the first screenshot I can navigate and expand/collapse the TOC pretty easily and it doesn't change the page that I am currently on (this is what I'm seeing locally). The second screenshot taken from your link above requires you to physically go to getting_started/index.html to subsequently see that expanded, which makes for a very strange and difficult navigation experience.

It's tough to see in the screenshots but everything in the first has a plus sign for expansion to the left of it, whereas again with the second you have to physically navigate to a different page for the TOC to expand.

or either you set it to a larger depth, but then once you expand this in eg the IO user guide page, the left sidebar gets so long that you don't see a lot of the navigation any more and you need to scroll inside the navigation. By splitting the navigation in eg a top bar and a left side bar, you can try to prevent this to a certain extent.

Yea I was going to see what setting this to three yield but didn't have time to wait for it today (certainly takes more time to build with this setting). IMO expanding / collapsing in the RTD theme is much nicer than physically having to click through pages and deal with split navigation bars in the bootstrap theme.

[jorisvandenbossche]

but didn't have time to wait for it today (certainly takes more time to build with this setting)

Take a look at the online version: https://pandas-dev.github.io/pandas-sphinx-theme/pr-readthedocs-theme/user_guide/io.html (that was also the goal of the pandas-sphinx-theme repo, it is set up to build the docs for different themes to easily compare them)

[jorisvandenbossche]

IMO expanding / collapsing in the RTD theme is much nicer than physically having to click through pages and deal with split navigation bars in the bootstrap theme.

OK, I see now what you mean (I added it to the online version, should be updated in a few minutes).
If that is something we want, that should not be hard to add to any other theme as well I think. At least for the sidebar, not for the top bar, if those are splitted as in my demo. So you could explore the navigation to the different pages within the user guide without actually going to that page, but eg not of the pages of the getting started section while you are in the user guide.
Personally that is not something I care about (at least not between the big sections, for within eg the user guide, I see how it can be useful, although it's a reflex of mine to do). That shows again how different people quite differently use websites, making it harder to find agreement here :-)

[BrittonWinterrose]

For some other examples (next to https://getbootstrap.com/docs/4.3/getting-started/introduction/) that have a nice theme ("nice" in my opinion = allow good navigation for more complex docs + looks good):

• https://sourcethemes.com/academic/docs/
• https://squidfunk.github.io/mkdocs-material/

Both could also be used as a starting point (take there theme + adapt templates to work with sphinx). The "academic" one is also based on bootstrap, the "material" one based on Material Design.

@jorisvandenbossche The "material" template is beautiful with clean fonts, no crowding, and great readability. I would pick that one over any of the others in this thread.

I would appeal to avoid updating the documentation to an "RTD" module, as a less-beautiful but familiar "status quo" is still quicker to navigate for most users than a new design.

As someone "new" to data science and programming when I come across the documentation for a project using the "RTD" format I am a bit weary, as many new (possibly unstable) packages use the documentation. And being new I've found myself reading a TON of documentation.

I understand that this perception may not be universal, but it seems like most established projects are eager to move away from RTD rather than towards it. I don't think RTD sends the right message to users for a project this mature and broadly adopted.

[jreback]

is there to rendering of what we are thinking about for a new theme / docs look? @jorisvandenbossche @datapythonista doing a talk on some new things going on and want to show a graphic.

[datapythonista]

I've just got this proof of concept online: https://pandas-dev.github.io/pandas-sphinx-theme/pr-datapythonista_base/index.html

I've got a branch with just the theme change locally, I can publish the result tomorrow.

[jreback]

@datapythonista awesome, just looking for a single screen shot thanks

[datapythonista]

This is what we've got so far, hope it works.

[jorisvandenbossche]

An update on this: @stijnvanhoey and I have been working recently again on a minimal bootstrap theme (from scratch, not based on the existing sphinx-bootstrap-theme, but my long term goal is to upstream some changes).

This can currently be seen at https://dev.pandas.io/pandas-sphinx-theme/user_guide/reshaping.html

The focus for now was mainly on structure and functionality (making sure we got the right content in the right in the right place, automatically setting up the different navigation sections, ..), and not yet on the styling of the details (and sphinx-specific styling). But that should come next (and a final styling will also only be possible when the new logo is available).

[jorisvandenbossche]

I opened a PR (#28623) to propose to start using the new sphinx theme for the dev docs.

The theme is certainly not yet fully ready (API tables are ugly, max-width is needed, nicer styling of highlighting active navigation items, ... see issues at https://github.com/pandas-dev/pandas-sphinx-theme/).
But I think it is currently at a good enough state to start using it for the dev docs, so it gets some exposure.

Feedback on the functionality / usability / look of the theme is very welcome. You can open issues at https://github.com/pandas-dev/pandas-sphinx-theme/, or I can also open an issue in the pandas repo here to gather feedback?
(note, there are a few known problems, notably the API summary tables are ugly)

[jorisvandenbossche]

I am going to suppose that silence is approval, so merging the PR later today unless I hear anything.

But note that concrete feedback on the new theme is still very useful (but maybe easier to give once it is actually merged in master). Once merged, I will open a new issue to gather feedback.

[jorisvandenbossche]

I am going to close this as we now have a new theme for the development docs (https://dev.pandas.io/docs/), and opened an new issue (#28952) to collect feedback on that.