DOC: collect feedback on new sphinx documentation theme

[jorisvandenbossche]

As discussed in https://github.com/pandas-dev/pandas/issues/15556 and activated in https://github.com/pandas-dev/pandas/pull/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 https://github.com/pandas-dev/pandas-sphinx-theme/pull/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 https://github.com/pandas-dev/pandas-sphinx-theme/issues/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: https://github.com/pandas-dev/pandas-sphinx-theme/issues/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 https://github.com/pandas-dev/pandas-sphinx-theme/issues/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 (https://github.com/pandas-dev/pandas-sphinx-theme/issues/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: https://github.com/pandas-dev/pandas-sphinx-theme/issues/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

[timhoffm]

Looking at https://dev.pandas.io/docs/reference/series.html

• The <h2> headings feel too large. With 2.5rem they are almost not distinguishable from <h1> (3rem). And too big compared with the text. I recommend going with 2.25rem for <h2>, see also https://typecast.com/blog/a-more-modern-scale-for-web-typography.

• The padding of the table cells is too large. You can now only see less than half the entries compared to the old theme. This reduces usability of the overview pages a lot.

[TomAugspurger]

On point 1, in https://github.com/pandas-dev/pydata-bootstrap-sphinx-theme/pull/63#issuecomment-567203505 we deliberately increased the isze of h1 and h2 to distinguish them from h3 headers. Not saying the the values I picked are best, but I want to keep that h2 vs. h3 distinction clear.

[westurner]

"BUG,DOC: responsive/mobile page width and left/right scrolling" #30910

[zertrin]

It would be nice to be able to switch between docs versions more easily. Not everyone is already using the latest released pandas version (might take some time to port code), and google usually brings you to the latest version.

Usually at readthedocs there is a version switcher in the bottom left of the page (bottom of the side bar). I have been desperately looking for something similar for Pandas docs...

What makes it worse it that if landed on the current docs, it is absolutely impossible to click your way through the correct location where to find previous docs. You need to know that you need to manually go to pandas homepage (https://pandas.pydata.org/) (not the docs homepage) by editing the URL for example, and then look in the "Previous versions" right sidebar for the docs link of previous releases. Very tedious.

The docs page are akin to a black hole in terms of version switching...

[westurner]

Could a few rules in Python or a config file specify which subpath of a git repo to copy _build/html to, generate a JSON file mapping versions to URLs for a dropdown control, copy the latest JSON version-URL map to every subpath, and update the /en/latest/ symlink (in order to store multiple versions of the built HTML docs in one repo)?

"How to build [Sphinx docs locally] with the ReadTheDocs Docker container" https://github.com/ammaraskar/sphinx-action/issues/9#issuecomment-586657133 ( Sphinx-action creates pull request reviews with inline Sphinx errors (with GitHub Actions; which could build the docs with the appropriate version of pandas and all dependencies already-installed in a container))

On Tue, Feb 18, 2020, 11:10 PM zertrin notifications@github.com wrote:

It would be nice to be able to switch between docs versions more easily. Not everyone is already using the latest released pandas version (might take some time to port code), and google usually brings you to the latest version.

Usually at readthedocs there is a version switcher in the bottom left of the page (bottom of the side bar). I have been desperately looking for something similar for Pandas docs...

What makes it worse it that if landed on the current docs, it is absolutely impossible to click your way through the correct location where to find previous docs. You need to know that you need to manually go to pandas homepage (https://pandas.pydata.org/) (not the docs homepage) by editing the URL for example, and then look in the "Previous versions" right sidebar for the docs link of previous releases. Very tedious.

The docs page are akin to a black hole in terms of version switching...

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/pandas-dev/pandas/issues/28952?email_source=notifications&email_token=AAAMNS3HALYVGYDAK4GTGUDRDSWLDA5CNFSM4JAF3XJ2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEMGI6HQ#issuecomment-588025630, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAMNSYKZC7O5RXHZILC7OLRDSWLDANCNFSM4JAF3XJQ .

[westurner]

Also, generating a /sitemap.xml which links to each subpath/sitemap.xml might improve search indexing for /en/v0.9.X/ /en/v1.0.X/ /en/latest/

On Wednesday, February 19, 2020, Wes Turner wes.turner@gmail.com wrote:

Could a few rules in Python or a config file specify which subpath of a git repo to copy _build/html to, generate a JSON file mapping versions to URLs for a dropdown control, copy the latest JSON version-URL map to every subpath, and update the /en/latest/ symlink (in order to store multiple versions of the built HTML docs in one repo)?

"How to build [Sphinx docs locally] with the ReadTheDocs Docker container" https://github.com/ammaraskar/sphinx-action/issue s/9#issuecomment-586657133 ( Sphinx-action creates pull request reviews with inline Sphinx errors (with GitHub Actions; which could build the docs with the appropriate version of pandas and all dependencies already-installed in a container))

On Tue, Feb 18, 2020, 11:10 PM zertrin notifications@github.com wrote:

It would be nice to be able to switch between docs versions more easily. Not everyone is already using the latest released pandas version (might take some time to port code), and google usually brings you to the latest version.

Usually at readthedocs there is a version switcher in the bottom left of the page (bottom of the side bar). I have been desperately looking for something similar for Pandas docs...

What makes it worse it that if landed on the current docs, it is absolutely impossible to click your way through the correct location where to find previous docs. You need to know that you need to manually go to pandas homepage (https://pandas.pydata.org/) (not the docs homepage) by editing the URL for example, and then look in the "Previous versions" right sidebar for the docs link of previous releases. Very tedious.

The docs page are akin to a black hole in terms of version switching...

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/pandas-dev/pandas/issues/28952?email_source=notifications&email_token=AAAMNS3HALYVGYDAK4GTGUDRDSWLDA5CNFSM4JAF3XJ2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEMGI6HQ#issuecomment-588025630, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAMNSYKZC7O5RXHZILC7OLRDSWLDANCNFSM4JAF3XJQ .

[jorisvandenbossche]

@zertrin yes, a version dropdown is on the to do list: https://github.com/pandas-dev/pydata-bootstrap-sphinx-theme/issues/23, I also really would like to see this (note this was a problem with the previous sphinx theme as well, although now there is also an issue in finding the home page -> https://github.com/pandas-dev/pandas/issues/30896)

[jbrockmendel]

@jorisvandenbossche is this actionable/closeable?

[glenpike]

I'm curious why the sidebar navigation is not sorted alphabetically. I can understand grouping methods in the index page for something like DataFrame, but as a n00b to the library, it's really hard to find functions that people mention in tutorials, etc.

[westurner]

Are they currently source-ordered?

As a workaround (for what could be a conf.py setting) can you Ctrl-F for the documented callable you're looking for?

On Wed, Jul 7, 2021, 08:51 Glen Pike @.***> wrote:

I'm curious why the sidebar navigation is not sorted alphabetically. I can understand grouping methods in the index page for something like DataFrame, but as a n00b to the library, it's really hard to find functions that people mention in tutorials, etc.

[image: Screenshot 2021-07-07 at 13 50 08] https://user-images.githubusercontent.com/789846/124762086-66b9b880-df2a-11eb-974f-2b4837029d33.png

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/pandas-dev/pandas/issues/28952#issuecomment-875576272, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAMNS2UDO6EOPV4E5J5SSTTWREVPANCNFSM4JAF3XJQ .

[glenpike]

Are they currently source-ordered? As a workaround (for what could be a conf.py setting) can you Ctrl-F for the documented callable you're looking for?

Hi, yes, I can try to find them - which works if I know what the method is. Not sure about the ordering 🤷 Thanks :)

[rhshadrach]

@jorisvandenbossche is this actionable/closeable?

I think no. Closing.