Update areas

[kgoebber]

Description Of Changes

This is a first pass at updating the ways that the areas baked into the declarative syntax works. I've captured 331 areas (a subset of what was in our original list) and have them corresponding to both an extent and a Cartopy projection. This is all contained in a separate file now and removed from the declarative file. These areas, their extents, and the projections are also available outside of the declarative syntax as well, which is captured the tutorial.

In adding elements to the docs I've attempted to capture things in a tutorial as well as a separate listing of all of the areas with a graphical representation of those areas with their long descriptive name. This generates 331 images, so the build of the docs takes longer, but if the file is not changed, then the caching of the images works as intended.

Still to do is to add tests.

Open to suggestions about organization of any of this material.

Checklist

• Closes Declarative Syntax Area descriptions #2526
• Tests added
• Fully documented

[dopplershift]

1. Any chance area_data was generated so that you could change it easily? I have some performance concerns about creating that many tiny dictionaries at import-time, only to throw them away (vs. e.g. named tuples).
2. I'm not wild about checking in a generated file. Do we really need it committed?

[kgoebber]

1. It was partially generated - manually did some line wrapping because of character limit, but if I take the time I should be able to do that as well. I can look at using a named tuple instead - initially went with what I knew (e.g., dictionaries) - but I'm not wedded to that if there would be better performance/better data object to use.
2. I tried to have the area.rst generate during the build, but I couldn't seem to find the right incantation of things through all of the sphinx docs settings, etc without a lot of excess stuff being generated as we have set up for a tutorial or gallery page. Reading of the Sphinx documentation was not yielding any clear paths to me from what I was able to find. In the end, I took the inspiration from Cartopy for the generation of their projections list. I would love to have that auto generate instead of committing a generated file.

I'll start looking at a named tuple for creating the areas and if there are any resources you want to point me toward for being able to auto generate the documentation file, I would be very happy to entertain.

Any other thoughts about functionality or organization of the information/documentation?

[kgoebber]

Okay, so I've updated this PR with what ended up being a very simple way of generating the area.rst file to both make files. I removed the committed area.rst and we should be relying on the autogenerated one from the Python file.

[dcamron]

Would you mind test out using def setup(app) in conf.py, basically a built-in Sphinx Extension to run your area generation script? It should work to run your Python code before building the docs whenever we call sphinx build.

If you find yourself needing to hand this off, I can dig into that, but it could let us keep your script as part of our sphinx tooling and out of the separate make machinery.

[kgoebber]

Okay, couldn't find a way with a more specific sphinx way of creating the areas.rst file, but I have been able to bake in a method for running the make_areas.py file within conf.py, which seems more robust than adding it to Makefile and make.bat.

[dopplershift]

I've got the best path to integrate with Sphinx here figured out. I'll push some changes to this PR.

[dopplershift]

So this isn't much different than what was done (running inside conf.py), but we can list pretty much any Python file in the same directory as conf.py as an extension. That extension then has setup(), which registers a callback for an event, which in our case we wait for the "builder" to be initialized.

Other than that it's the same code, though it relies on Sphinx to know some proper paths and give us a logger. Sphinx doesn't have much better in the way of hooks to grab, but this does seem a bit more structured than running a script every time conf.py is imported. It's actually the same way Sphinx's own autosummary extension is wired in.

[dopplershift]

@dcamron This will need your review since I've now committed on the PR.

[dopplershift]

Sorry, finally noticed a few things here.

If you can't get to them before (trying to) release tomorrow, I'll take care of them.

[kgoebber]

I was able to make the requested changes, but don't have the correct method of exposing the named_areas from plots directly and not run afoul of import things. I think you all will have to take it from here.

[dopplershift]

I confirmed that the default to dynamically control whether we generate ALL the areas is working properly on CI vs. locally. This is a significant time savings for building locally (when you don't actually care about having them all).

[dcamron]

👍 thanks y'all for getting this all there!