Enhance Cube slicing docs

[hsteptoe]

🚀 Pull Request

Description

Some relatively minor enhancements to the docs for the cube.slices() and cube.slices_over().

• Made some of the wording clearer
• Modified examples to use iris-sample-data
• Added example of using dimension indices for slicing.

---

Consult Iris pull request check list

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 89.77%. Comparing base (7c313ff) to head (13abd1a).
Report is 12 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5735   +/-   ##
=======================================
  Coverage   89.76%   89.77%           
=======================================
  Files          93       93           
  Lines       22982    22995   +13     
  Branches     5006     5011    +5     
=======================================
+ Hits        20630    20643   +13     
  Misses       1622     1622           
  Partials      730      730           

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

[hsteptoe]

N.B. I've aimed for judicious use of # doctest: SKIP directive to deal with cases where example output would be too long to be useful, or where I seem to get stuck in a linter-modified-test-fail loop with cube printing

[CLAassistant]

All committers have signed the CLA.

[trexfeathers]

Thanks @hsteptoe, and sorry for the delay.

This is a really valuable addition for an area that I personally regularly forget - examples are gold!

I felt it was important to get the doctests working, to make sure the code continues working in perpetuity. I was able to test and iterate the formatting locally using this handy command (run within an Iris development environment, within the /docs/src directory):

sphinx-build -b doctest -d _build/doctrees   . _build/doctest generated/api/iris.cube.rst

The suggestions work, and pass the pre-commit checks.

[trexfeathers]

Brilliant, thanks again!