Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DOC: collect feedback on new sphinx documentation theme #28952

Open
jorisvandenbossche opened this issue Oct 13, 2019 · 23 comments
Open

DOC: collect feedback on new sphinx documentation theme #28952

jorisvandenbossche opened this issue Oct 13, 2019 · 23 comments
Labels
Docs

Comments

@jorisvandenbossche
Copy link
Member

jorisvandenbossche commented Oct 13, 2019 •
edited
Loading

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.
@jorisvandenbossche jorisvandenbossche mentioned this issue Oct 13, 2019
Closed
@sara-02
Copy link
Contributor

sara-02 commented Oct 29, 2019

@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
Copy link
Member Author

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
Copy link

tritas commented Oct 30, 2019

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
Copy link
Contributor

sara-02 commented Oct 30, 2019

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

@mangecoeur
Copy link
Contributor

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
Copy link
Member Author

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
Copy link

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
Copy link

kavvkon commented Oct 30, 2019

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 jorisvandenbossche mentioned this issue Oct 30, 2019
Closed
@jorisvandenbossche
Copy link
Member Author

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
Copy link

kavvkon commented Nov 4, 2019

@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
Copy link
Member Author

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
Copy link
Contributor

kokes commented Nov 10, 2019

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'
)

Screen Shot 2019-11-10 at 5 36 27 PM

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

@timhoffm
Copy link
Contributor

timhoffm commented Jan 3, 2020 •
edited
Loading

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
Copy link
Contributor

On point 1, in pydata/pydata-sphinx-theme#63 (comment) 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
Copy link
Contributor

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

@westurner westurner mentioned this issue Jan 12, 2020
Closed
@zertrin
Copy link
Contributor

zertrin commented Feb 19, 2020

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
Copy link
Contributor

westurner commented Feb 19, 2020 via email

@westurner
Copy link
Contributor

westurner commented Feb 19, 2020 via email

@jorisvandenbossche
Copy link
Member Author

@zertrin yes, a version dropdown is on the to do list: pydata/pydata-sphinx-theme#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 -> #30896)

@jbrockmendel
Copy link
Member

@jorisvandenbossche is this actionable/closeable?

@glenpike
Copy link

glenpike commented Jul 7, 2021

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.

Screenshot 2021-07-07 at 13 50 08

@westurner
Copy link
Contributor

westurner commented Jul 7, 2021 via email

@glenpike
Copy link

glenpike commented Jul 7, 2021

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 :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Docs
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests