-
-
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
WEB/DOC: integration of the main website and documentation #28580
Comments
Worth noting for the items in the navigation bar, that we've got some discussion with NumPy to standardize all that makes sense (numpy/numpy.org#43). I'm personally very happy with what we discussed, I'm generating a version of the website with what I think it makes sense for pandas based on the discussion. I think 3 is what makes more sense. I'd start by something as simple as creating a theme directory in the repo, with the layout of the web, and use it in the docs too. I guess it'll require few changes, but I created the layout of the website with Sphinx blocks, so shouldn't require so many changes. The navigation bar is populated from a yaml, I think we should parse the yaml in the Sphinx settings and add it to its context. But I think that would be a good first step, and we'll see if this looks like the right direction or not. |
OK, that seems an interesting discussion, will need to read up on that. One note though, that from a seeing their current sitemap idea (and also current docs), is that numpy is actually doing option 1: link from the website, but the docs itself are a separate entity (which also eg Julia is doing) |
If you say that you would prefer option 3, can you be a bit more detailed? Do you mean with the current "Documentation" dropdown? (as I said above, and before in person I think, I am not a fan of such a dropdown for the main items of docs)
That's sounds as a good option to get it in sphinx (at least in the static html of the latest version, question is still if we are OK with that for stable + older versions) . As a first step, I wouldn't care too much about automation like that, but first experiment and decide with a certain design. |
I think having a unifier navigation in all pages including the docs has a lot of value. Many people will land in the docs directly (e.g. Changing the items of the navigation depending on where you are seems confusing to me (like showing "About us" in the home, and "API reference" in the docs). Then, the two options I'm happy with are having just the top navigation bar (and then the sidebars you're building), or having the second bar in your prototype. My preference is the first, not having the second bar, mainly because:
Removing the dropdown in "Documentation" and having the second bar instead sounds reasonable. But I don't see why a dropdown should be a bad thing, and I don't think we want to add even more complexity than the two sidebars to our website. css really sucks, and the last thing we want to spend time with is in having to deal with issues of "your css is broken in X browser". I'd take what bootstrap gives us for free, and not overcomplicate things, if it's just for a personal preference on dropdowns, and there is nothing else that I'm missing. In any case, worth moving forward one step at a time, and create drafts of the different options once we're in that stage. Will be easier to discuss in practice than in theory I think. |
That might well be, but that's how it is in almost all projects that we were comparing with in one of the other issues (numpy, jupyter, spark, julia, ..). They all have a separate website and separate docs, with just a link from the one to the other.
Agree that that would be confusing (that's not what I wanted to suggest, sorry if that was not clear).
To me, the fact that they are not in a dropdown is a significant value.
That's not my current idea for the theme (see the prototype at http://dev.pandas.io/pandas-sphinx-theme/user_guide/index.html), but feedback on it is very welcome.
Personally, I find dropdowns often a poor UX (often, not always). In this case, having the main navigation level of the docs in a dropdown means an extra click to move there + makes it somewhat hidden. Some examples for possible inspiration: Django is an example where they have a common header, also on the doc pages: https://docs.djangoproject.com/en/2.2/ref/applications/ (but they don't really have a second nav bar, although they have a bar with "Documentation" title and the search box) Mapbox docs is an example of two navbars, where the top one disappears when scrolling down (in our case the top one could be the main website one): eg https://docs.mapbox.com/mapbox-gl-js/api/ (personally, on their site and their styling, I don't find this "too much") Docker also has the main website navigation on their doc landing page: https://docs.docker.com/ (at the full top is the main website navigation, below the "Docker Documentation" banner is the main doc navigation, and when scrolling down, this one sticks at the top). |
Don't have time to work on this now, but to summarize what I'd do:
And as I mentioned, keep the top bar common. I'd just have that bar, but happy to have a second bar for the docs, since you seem to have a strong preference on that. |
FYI, https://dev.pandas.io/about/index.html is not loading CSS. |
The "Whats new in 0.25.3" link on the homepage takes you to the 0.25.0 whats new page instead of the 0.25.3 page. |
Currently releasing 0.25.3 and not announced yet, so might be some broken links during that process |
Thanks for reporting @kylekeppler, I opened #29325 for this. |
With the new markdown based website (#28014) and the new sphinx documentation theme (#15556, https://dev.pandas.io/pandas-sphinx-theme/), we need to see how to integrate both.
Roughly speaking, I can currently think of three options:
I did a quick experiment for this: https://dev.pandas.io/pandas-sphinx-theme/pr-integration-website-double-navbar/. Right now this looks ugly of course due to the non-matching styles and alignment, but to give the idea and I think this can be made look nice with matching styles.
(TODO: will also do an experiment for this option)
Short term we can use the first option (eg if we want to start using the new theme on the dev docs this week), but I think ideally we want to go to a more integrated option?
Besides the choice on how we want it to look, there is also a technical issue to solve: how to put this common navbar in the docs?
We can hardcode this in the html (when building it can eg be included in the layout from a file shared with the website), but this means that this navbar is fixed for older versions of the documentation, and if we do updates to the website this might not match with the header navbar of the released documentation.
The text was updated successfully, but these errors were encountered: