New theme and organization for docs

[dopplershift]

Description Of Changes

In my never-ending quest to rearrange the deck chairs on the Titanic find new infrastructure improvements for MetPy, I stumbled across the pydata-sphinx-theme, which is used to power Pandas' docs among other projects. I was inspired and decided to try applying the theme to our docs.

The initial port made clear we had too many top-level topics, so it led to a further hack-and-slash re-organization that left us with 4 main top-level headings: User Guide, Examples, Reference Guide, and Developer's Guide; there's also a link at the top to our support resources, as well as external links to the Python Training gallery and our GitHub releases. Altogether, this re-org starts to address #1041, #1351, and #1445. The result is:

You can view the new site here as well.

Gains:

• Nice and clean, and fits a bit better with newer Unidata docs like netCDF-java
• We have a banner that can be populated with news items simply by adding a single HTML in the root of the gh-pages branch--making it appear on all the docs with this theme
• Banner noting when one is looking at old or dev/pre-release docs
• Vastly simplified landing page with explanations for what the sections are
• We no longer need our static, out-dated build of the RTD theme

Still todo:

• Clean-up organization of consolidated sections (would appreciate suggestions)
• Maybe re-arranged logo for horizontal navbar?
• Decrease versions listed in selection menu
• Restore canonical_url in generated HTML--something we had with RTD that helps Google, etc. prefer our /latest docs.

Also, my sphinx, as well as bootstrap+CSS, fu has increased in doing this so lots of things are relatively possible. For instance, inserting the version controller was not a huge deal (though I do want to upstream some changes so I don't have to override the entire navbar HTML file just to add it).

I'm open to any and all feedback on styling, structure, and content organization.

Credit goes to Bokeh's docs for the banner idea and help on how to do the version chooser. Pandas showed how to achieve the front page cards.

Checklist

• Closes #xxxx
• Fully documented

[dopplershift]

Ping @ddirks, if you have even 5-10 minutes to spare on styling or organization, it would be greatly appreciated. We can always revise later, but good to put our best foot forward...

[jthielen]

On an initial impression, this looks great! I'd definitely vote in favor of moving to this theme. I've been a fan of it ever since I found out about it at SciPy (particularly since it uses Bootstrap), and it sounds like it was a good motivation for reorganizing the content structure of the docs.

I can take a closer look once certain other things are done, but I definitely agree with the to-do items you pointed out. To add to them/go in more detail:

• The negative space on the homepage (for the usual secondary nav) on the left side feels off somehow. Not sure if it would be good to add in a copy of the primary nav items there, since it is where your eyes are drawn in this theme to get to a new place, or something else.
• The secondary nav in the examples section needs some attention. Right now, there is no clear ordering or hierarchy to it.
• The Developers Guide top-level page could use some additional content to appropriately direct to subpages, or perhaps even a restructuring of that section for the new design could be helpful
• This theme has known issues with xarray's HTML repr, which I was planning on making full use of in the 1.0 update docs (assuming Pint's HTML repr can get updated in time as well). So it would be good to push for an upstream fix there before going live with this.

[dopplershift]

If anyone is curious about the icons for the cards on the main page, they're from Font Awesome which was already included. Other suggestions welcome.

[kgoebber]

I love the top nav bar and use of the headlines to help users interact in desirable ways with things related to MetPy (e.g., the survey). Overall I like the big boxes that describe the different areas of the Docs. That will help to get users to the content they need.

I largely agree with all of the comments already provided by @jthielen, especially the negative space on the main page and to a lesser extent on the other pages. The left nav bar should probably be smaller, especially on the home page.

With all of the negative space, the page is very white and bright, could use a touch more color, even if just the icons associated with the different subpages had a background color associated with them, or something similar.

On the main page, would it be possible to have the User Guide and Reference Guide on top, with the Examples and Developer Guide on the bottom? That organization seems more natural to me. Additionally, can the icons also be links? Seems like it would be beneficial to have a larger area that could be clicked on to get to the desired page rather than just the text name within each box.

On the GEMPAK Conversion page (The name should maybe be GEMPAK Comparison and Equivalence?) it would be nice to get the full table to appear directly on the page and not have to figure out how to scroll over to get to the actual comparison information cells.

Is there an ability to organize or at least add headers to content in the left nav bar on certain pages (e.g., examples and calc pages)?

That's all I've got right now...great work, in the end this is a good iteration of the docs!

[dopplershift]

Ok, latest push doesn't do much to content, but:

• Updates to latest from upstream
• Incorporates some of the tweaks @ddirks made, including a new logo (Thanks!)
• Adds a splash of color and alignment on the front page cards

What remains for the merge on this I think is taking a pass through making the re-organization of content better. I don't want to hold this up for some of the sidebar and other theming/styling issues--we can handle those going forward. I'll make a pass through content next.

[jthielen]

Not sure how relevant this is given the current timeline of the release, but the xarray repr issue I mentioned earlier with this theme is fixed on master (pydata/pydata-sphinx-theme#274), but not yet released. Right now I think this only breaks the isentropic interpolation example with the dataset being missing (examples/isentropic_example.html), but I'm not sure where else we were relying on the xarray HTML repr yet.

[lgtm-com]

This pull request introduces 1 alert when merging 5b47012 into 49e041d - view on LGTM.com

new alerts:

• 1 for Variable defined multiple times

[jthielen]

CSS border/color changes talked about on telecon:

• Adjust .intro-card to have background: #D8E5E8; and border: none; in theme-unidata.css:35
• Add shadow class to nav#navbar-main

[jthielen]

@dopplershift would you be able to add this css with the xarray override?

.xr-var-data pre {
  border: none;
  box-shadow: none;
}

[lgtm-com]

This pull request introduces 1 alert when merging 4c305f2 into 49e041d - view on LGTM.com

new alerts:

• 1 for Variable defined multiple times

[lgtm-com]

This pull request introduces 1 alert when merging 9adc91e into 49e041d - view on LGTM.com

new alerts:

• 1 for Variable defined multiple times

[dopplershift]

Everyone was happy with how this looks on the call, so now that we're green (except for Code Climate for some reason) in it goes...