Add strict option to sphinx extension

[jtilly]

Closes #2550

This adds a :strict: option to the altair sphinx extension. When set, it ensures that the documentation build fails when a code snippet can't be run. This is meant to prevent code snippets in the documentation from going stale. It is less restrictive than building the documentation with -W because warnings for other reasons won't cause the build of the documentation to fail.

[jakevdp]

Perhaps raise ValueError(message) from e to allow the error to include more context.

[jakevdp]

Looks good - I wonder if it would be worth adding a :strict: option to altair-gallery as well, which could forward it to the generated altair plots?

[jtilly]

I'm not 100% sure what you mean, but I gave it a shot anyways: in eaf69c1 I imitated what's currently being done to the :code-below: flag.

[jakevdp]

Yeah, I forgot that there's no gallery directive. That looks good.

Last thing: since there are no unit tests to exercise this option, have you tried it locally to confirm it works as expected?

[jtilly]

Have you tried it locally to confirm it works as expected?

Yes!

With

.. _test:

====
Test
====

.. altair-plot::
    :output: none
    :strict:

    {1} + [2]

I get

/tmp/altair/lib/python3.9/site-packages/altair/sphinxext/altairplot.py:229: UserWarning: altair-plot: /tmp/doctest/docs/test.rst:7 Code Execution failed:TypeError: unsupported operand type(s) for +: 'set' and 'list'
  warnings.warn(message)

generating indices... genindex py-modindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 13 warnings.

and with :strict: I get

.. _test:

====
Test
====

.. altair-plot::
    :output: none
    :strict:

    {1} + [2]

writing output... [100%] test                                                                                                                                                                                                                 
Exception occurred:
  File "/tmp/altair/lib/python3.9/site-packages/altair/sphinxext/altairplot.py", line 227, in html_visit_altair_plot
    raise ValueError(message) from e
ValueError: altair-plot: /tmp/doctest/docs/test.rst:7 Code Execution failed:TypeError: unsupported operand type(s) for +: 'set' and 'list'
The full traceback has been saved in /var/folders/gj/hb6rghv906vdldwzwg13bm3m0000gn/T/sphinx-err-8f07v1lb.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [Makefile:20: html] Error 2

[jakevdp]

Very nice - thanks!