add sphinx documentation build to CI

[wholmgren]

A handful of recent PRs have broken the documentation build. We should add the documentation build to the azure pipelines CI configuration and fail it if the documentation errors.

[Peque]

Maybe you want to have a look at Autobuild Documentation for Pull Requests, since you are already using Read the Docs and GitHub.

[wholmgren]

Nice, thanks. My reading is that it's currently only available for readthedocs itself. Hoping I'm wrong or that it becomes more widely available soon. I imagine they might be faced with a large increase in compute needs.

[Peque]

Yeah, it is in beta. You can currently email them to enable the feature. Just wanted to link it here in case you want to try it early or in case it comes out of beta before anybody fixes this issue.

They will probably be faced with a large increase in compute needs, yeah, but I hope they can compensate that with paying subscriptions, as this was a largely requested feature for private repositories as well. 😊

[wholmgren]

Thanks, I emailed them.

[wholmgren]

RTD added us the the beta program and I modified our RTD webhook to support PR doc builds. Docs for existing PRs will be built after a new commit is pushed. For example: https://external-builds.readthedocs.io/html/pvlib-python/773/index.html

Thanks again for pointing out this feature!

[CameronTStark]

I've been thinking about the gallery contributions and wondering how they can be tested within the CI. I'd like to make sure that these contributions are kept up to date with API changes so newbies don't have to worry about broken examples.

I'm just starting to explore this and might open a separate issue to address but I at least wanted to begin to explore the idea here.

[kandersolar]

It's not a full test in that it doesn't check for expected output, but sphinx-gallery has some built-in handling for broken tests: https://sphinx-gallery.github.io/stable/configuration.html#dealing-with-failing-gallery-example-scripts

[CameronTStark]

Thank you for that @kanderso-nrel. An error will be raised which should fit our needs with the CI.

[mikofski]

Sphinx had built in doctests. Enable it like any other extension by adding sphinx.ext.doctest to the conf.py. SciPy uses this so that all examples are legit. It doesn't run on the CI, but the docs won't build on RTD if any examples fail.