How should pvlib.iotools be showcased in the documentation?

[kandersolar]

pvlib.iotools is one aspect of the package that sets pvlib apart from other PV modeling software, but its presence in our documentation is pretty scant outside of the API listing. I think gallery examples of fetching and using data would be very cool, but given the nature of some of the APIs we support (slow, unreliable) I'm a little wary of the maintenance burden those examples might bring. However I still would like to show them off, so here is some brainstorming, stemming from a conversation w/ @AdamRJensen:

1. sphinx-gallery supports including examples in the gallery without actually executing them. I guess we could even use normal RST to include pre-generated plot images for the expected output if we wanted the example to have visuals without needing to execute anything, but that would be its own maintenance burden. https://sphinx-gallery.github.io/stable/configuration.html#parsing-and-executing-examples-via-matching-patterns
2. Use pre-executed Jupyter notebooks instead of .py files so that the notebooks don't have to be run on each docs build to get the output. RdTools uses this approach because we didn't want to bog down docs builds by executing examples. We would have to add some new docs dependencies and create a separate gallery, as I don't think there's any way to integrate notebooks w/ sphinx-gallery (see Support jupyter notebooks sphinx-gallery/sphinx-gallery#245). Also I'm always reluctant to include notebooks in version control systems.
3. Normal RST pages not associated with any gallery, like our existing modelchain.rst. Not sure this has any benefit over option 1.
4. sphinx-gallery has built-in caching and doesn't execute examples that haven't changed since the last build. My understanding for how things work on RTD is that it's a fresh slate every time, meaning there is no "last build" to consult. Maybe it's possible to configure RTD to persist build artifacts across builds? I think we should not give up "clean slate builds" lightly though; I frequently run into sphinx weirdness that is only solved by make clean.
5. Something else?

Any thoughts? Of these I think I favor option 1, even if we decide not to curate the output images by hand. If no better solution presents itself I might play around with that and make sure it behaves as expected.

[mikofski]

Just show code sample for API calls for data retrieval, but don't execute. Some of these functions have ability to read a file like read_macc() then just cache the file some where easier to retrieve. A data repository or archive separate from pvlib might be useful. There may be some services out there already, like Git LFS, dropbox, and more sciency services. There was a scipy dev mail list discussion on this a few years ago. Ask them