DOC: collect feedback on new sphinx documentation theme

[jorisvandenbossche]

As discussed in #15556 and activated in #28623, the development docs are using a new sphinx documentation theme (for now developed in https://github.com/pandas-dev/pandas-sphinx-theme/).

You can see it in action at https://dev.pandas.io/docs/user_guide/index.html

But as with all new things there will be some rough edges / certain workflows that were easier before / things you don't like / ... with the new theme.
So feedback is very welcome! We can use this issue to collect feedback in this repo (and otherwise specific issues can also be opened at https://github.com/pandas-dev/pandas-sphinx-theme)

For the next release, I think most structural blockers are solved (search works now, tables are not completely ugly, second navigation level in left sidebar is not hidden anymore). But there are certainly a lot of improvements to be made regarding styling (typography, styling / coloring of inline code and links, ... width of the page) and mobile responsiveness.
In pydata/pydata-sphinx-theme#32 I am trying out some basic styling for indicating the current active navigation items.

[sara-02]

@jorisvandenbossche where do we add suggestions for typos?
Do we keep adding them here or create a new issue whenever we come across one?

[jorisvandenbossche]

where do we add suggestions for typos?

Typos are most probably typos in the actual doc sources, and not in the theme. So for those, you can create a PR fixing them if you want, or otherwise open a separate issue.

[tritas]

Hi, thanks for the work on the new theme, it looks modern and clean.

1. Do you think the purple mono-space font on the yellow and blue alert alert boxes is fine for users with color-blindness?
2. Looking at the copyright notice in the footer, what do you think if it were center justified and had a bottom margin of some pixels added to it?
3. Noticed that the copyright date range spans 2008-2014 in doc/conf.py and 2008-2012 in the License file. Is that correct? Sorry if the point isn't relevant to this issue.

[sara-02]

I agree with @tritas 2nd point about some sort of margin added to the copyright notice.

[mangecoeur]

Thanks for the work! My first impression is that the left/right split for the contents navigation is a little confusing - its not instantly obvious how the right navigation relates conceptually to the left one. Also the fact that it disappears with narrower windows is maybe not ideal, it's useful so why hide it sometimes?

[jorisvandenbossche]

Thanks for the feedback!

Do you think the purple mono-space font on the yellow and blue alert alert boxes is fine for users with color-blindness?

@tritas I am no expert in this, but from your question I assume the answer is "no" ?

Looking at the copyright notice in the footer, what do you think if it were center justified and had a bottom margin of some pixels added to it?

Yes, that's certainly something to improve. For pandas, we probably want the same footer as for the main website, but also in general a better footer by default for the theme would be nice. I opened pydata/pydata-sphinx-theme#42 to track this

My first impression is that the left/right split for the contents navigation is a little confusing - its not instantly obvious how the right navigation relates conceptually to the left one.

@mangecoeur There is an issue here about the content of the right sidebar: pydata/pydata-sphinx-theme#12. I image we could add something like "On this page" as a title on the right sidebar. Would that make it already clearer that the right sidebar is the local table of content for the page you are looking at?

Also the fact that it disappears with narrower windows is maybe not ideal, it's useful so why hide it sometimes?

That's part of the responsive aspect provided by bootstrap. If it would not disappear, other elements (the body, the left sidebar, which have priority over the right sidebar) would not have enough space anymore.

[kvanderwijst]

Hi Joris, looks good, much better than the previous theme.

Would it be possible to collapse the header to something much smaller (half the size?) when scrolling down? This leaves more room for the actual content, which is important for smaller screens ( = my laptop).

[kavvkon]

Much modern and cleaner, definitely an improvement! However, I think you should have a max-width of 900px -1000px in the middle column. To difficult to read when maximized in wide screens.
Moreover the subheaders should have some background for constrast. Right now the only constrast exists in the info boxes and when you scroll down fast you lose track where you are.

In general, I got the feeling that I could skim quicker to the info that I wanted with the old template but maybe I am just used to it

[jorisvandenbossche]

Thanks again for the feedback!

Would it be possible to collapse the header to something much smaller (half the size?) when scrolling down?

@kvanderwijst Yes, that's certainly something to consider (the logo should also shrink then). Another option would be to hide the header when scrolling down, and eg only show it again when scrolling up or at the top. Or just make it smaller to start with.
I opened pydata/pydata-sphinx-theme#43 to track this further.

I think you should have a max-width of 900px -1000px in the middle column. To difficult to read when maximized in wide screens.

@kavvkon Yes! I agree with that, and have been meaning to do that, but didn't come to it yet (pydata/pydata-sphinx-theme#17 as an issue for it)

Moreover the subheaders should have some background for constrast. Right now the only constrast exists in the info boxes and when you scroll down fast you lose track where you are.

@TomAugspurger gave similar feedback a few days ago: pydata/pydata-sphinx-theme#39 Feel free to give more detailed feedback on that issue!

In general, I got the feeling that I could skim quicker to the info that I wanted with the old template but maybe I am just used to it

@kavvkon Being used to it is probably part of the reason, but if you think later of more specific reasons, certainly interested to hear them.
Do you mean "skim to the info that I wanted" within a page? Or get quicker to the page that you know the information should be somewhere?

[kavvkon]

@kavvkon Being used to it is probably part of the reason, but if you think later of more specific reasons, certainly interested to hear them.
Do you mean "skim to the info that I wanted" within a page? Or get quicker to the page that you know the information should be somewhere?

Yes I mean within a page.. I guess the above issues on headers and a better contrast balance among headers, code boxes and info boxes will resolve this.

[jorisvandenbossche]

I guess the above issues on headers and a better contrast balance among headers, code boxes and info boxes will resolve this.

Yes, that part of the theme (styling the elements within the body: the headers, code boxes, links, etc) did not yet get much attention, so a lot of room for improvement there.

[kokes]

Great stuff! I checked the API reference and for longer methods, like read_csv, it's sort of a wall of black text (apart from the odd code block there) - have you thought about differentiating the sections in some way?

I did something extremely basic to illustrate my idea:

Array.from(document.getElementsByClassName('field-list')[0].getElementsByTagName('dd')).map(
	x=>x.style = 'border-bottom: 2px solid #eee; padding-bottom: .5em'
)

https://dev.pandas.io/docs/reference/api/pandas.read_csv.html