-
-
Notifications
You must be signed in to change notification settings - Fork 17.9k
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.
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
DOC: more modern sphinx theme #15556
Comments
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). |
@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). |
ok by me. |
That seems fine. |
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 |
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:
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) |
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 :-)) |
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]. |
(warning: long comment coming :-))
That was also not yet advertised, so that is normal :-)
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). 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. 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.
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). When we would go for such a more hierarchical structure, then the theme needs to support this.
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). 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. |
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: 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. |
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...
(an important item here is to lower the barrier to update te docs (just a direct link)
@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? |
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 What would you think if we start by opening a PR to the |
The reasons that I thought the separate repo was a good idea was for the following reasons:
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. (if I am making things too complicated, please argue so :-) ) |
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/...)? |
My main concern is working for too long with different copies of the documentation 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 |
just saw this: https://ofosos.org/2018/12/28/landing-page-template/ |
thanks, that's the same approach I'm already using in https://pandas-dev.github.io/pandas-sphinx-theme/pr-datapythonista_base/ |
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: |
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) |
@WillAyd (and others) to come back on #25614 (using the readthedocs theme for our docs). First, readthedocs ( 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). 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:
But it should give some idea of what is possible with a theme based on this. |
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 |
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): 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. |
Any others with an opinion about this (#15556 (comment)) ? |
starting with an existing already done theme that provides the sophistication as outlined here: #15556 (comment) is +1 from me |
I also updated the readthedocs version with the same subset of the current docs, for easier comparison:
|
@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)? |
@WillAyd for now I only switched I see that in that PR, you used in addition:
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 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. |
I agree with what has been said by both @WillAyd and @jorisvandenbossche
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:
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. |
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. |
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 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.
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. |
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) |
OK, I see now what you mean (I added it to the online version, should be updated in a few minutes). |
@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. |
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. |
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. |
@datapythonista awesome, just looking for a single screen shot thanks |
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). |
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/). 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? |
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. |
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. |
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:
(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/
The text was updated successfully, but these errors were encountered: