Feature: Documentation Revamp and Retheme

[freemansw1]

After #460, I started to poke around to figure out how to make things look better on our documentation. As it turns out, making the docs look and feel modern was really not all that much work. I also thought v1.6.0 would be an ideal time to produce new, modern-feeling documentation.

This represents just a first step. I have modified very little text, instead just reorganizing things into categories to fit the theme. Note that this is requested to be merged into a new dev_documentation_revamp branch, which comes off RC_v1.6.0. I'm putting this in a branch by itself to encourage more collaborative work on this; perhaps we can commit to that repo directly rather than doing it through PRs (until it is time to merge into the RC).

Given the somewhat unusual path here, I'm requesting relatively light reviews. We will continue to make updates before merging into the RC, I am at this point just seeking feedback on whether or not this is broadly fits what we are looking to do with our documentation.

• Have you followed our guidelines in CONTRIBUTING.md?
• Have you self-reviewed your code and corrected any misspellings?
• Have you written documentation that is easy to understand?
• Have you written descriptive commit messages?
• Have you added NumPy docstrings for newly added functions?
• Have you formatted your code using black?
• If you have introduced a new functionality, have you added adequate unit tests?
• Have all tests passed in your local clone?
• If you have introduced a new functionality, have you added an example notebook?
• Have you kept your pull request small and limited so that it is easy to review?
• Have the newest changes from this branch been merged?

[github-actions]

Linting results by Pylint:

Your code has been rated at 8.72/10 (previous run: 8.72/10, +0.00)
_{The linting score is an indicator that reflects how well your code version follows Pylint’s coding standards and quality metrics with respect to the dev_documentation_revamp branch.
A decrease usually indicates your new code does not fully meet style guidelines or has potential errors.}

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 62.27%. Comparing base (0ebee82) to head (0cecc40).

Additional details and impacted files

@@                    Coverage Diff                    @@
##           dev_documentation_revamp     #470   +/-   ##
=========================================================
  Coverage                     62.27%   62.27%           
=========================================================
  Files                            23       23           
  Lines                          3690     3690           
=========================================================
  Hits                           2298     2298           
  Misses                         1392     1392           

Flag	Coverage Δ
unittests	62.27% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[w-k-jones]

Looks really good! Happy for this to be merged into the docs development branch so further work can get started. Some thoughts, which can be addressed in later PRs:

• API documentation has no subsections in the left side column
• The home page is a bit unclear now, as it is just a block of text. We should think about how to restructure it to more clearly direct users to the info they need. I quite like the way that the numpy and xarray docs homepage is structured

[freemansw1]

Looks really good! Happy for this to be merged into the docs development branch so further work can get started. Some thoughts, which can be addressed in later PRs:

• API documentation has no subsections in the left side column

Yeah, I'll plan to fix that before the PR gets merged. Good call. I need to dig into that section some more.

• The home page is a bit unclear now, as it is just a block of text. We should think about how to restructure it to more clearly direct users to the info they need. I quite like the way that the numpy and xarray docs homepage is structured

One reason I didn't do anything to the homepage is that I am not sure whether we should go for something like the xarray/numpy/metpy documentation or more of a highlight gallery like the ArviZ documentation (https://python.arviz.org/en/stable/). I am inclined for the latter, but I am open to either.

[fsenf]

Nice look! I really like it. Well done, @freemansw1 !

A few minor comments:

• could we get rid of "Section Navigation":
  

• user guide starts empty:
  

• (I have issues to understand the hierarchy at the moment, I mean chapter -> section -> subsection, but this may come with time)