Adopt sphinx-apidoc and retire complex sphinxext

[tkknight]

🚀 Pull Request

Description

Retire the old and convoluted sphinx extensions to generate the Iris API documentation.

• Uses sphinx-apidoc instead
• The indented blank line is now gone that appeared at the top of some API doc pages
• The "In this module:" section is now not present (part of the old extensions), this is fine as the right hand sidebar shows this now.
• At the bottom of each page the TOC (Table of contents) for all child packages or modules is displayed. I think this is useful, especially if viewing on a smaller screen where the sidebar may be hidden.
• The order or sidebar contents are different but all are present
• The docstrings can be in a slightly different place but all are present I believe (I welcome someone doing a review to check some api doc pages)
• There is still a sphinxext (new one) that will remove the word package and module that make the sidebar hard to read imho. I cannot find any option in sphinx-apidoc itself to disable this.
  • Without package and module in the sidebar (and headings)
    • 
  • With package and module in the sidebar (and headings)
    • package and module in the sidebar (and headings)
      • 

There are many incorrect indentations and incorrect syntax in the docstrings that should be using the numpydocs, I may address those in a separate PR.

---

Consult Iris pull request check list

[trexfeathers]

OMG ❤

[codecov]

Codecov Report

Patch and project coverage have no change.

Comparison is base (cb287ce) 89.32% compared to head (f0dce12) 89.32%.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5264   +/-   ##
=======================================
  Coverage   89.32%   89.32%           
=======================================
  Files          89       89           
  Lines       22390    22390           
  Branches     5374     5374           
=======================================
  Hits        20000    20000           
  Misses       1640     1640           
  Partials      750      750           

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[rcomer]

😍

Think the linkcheck failure is matplotlib/matplotlib#25731

[bjlittle]

heart_eyes

Think the linkcheck failure is matplotlib/matplotlib#25731

There been a server outage for the mpl docs most of the afternoon, but it's back up now.

I respun the CI and all is well now 😄

[pp-mo]

Don't usually comment on docs PRs, but this one is a great improvement !
It all looks great to me -- couldn't see anything wrong + all the changes are beneficial.
🚀

[bjlittle]

@tkknight This is fantastic! 🥇

I've been waiting for us to purge the custom extensions for many years... that said, they've served their purpose very well indeed.

Since #5274 landed, which also changed the lock files, could you please rebase your PR and re-generate the lock files with your new sphinxcontrib-apidoc dependency.

Awesome thanks 👍

[pp-mo]

note: same in all 3 lockfiles ?