🧪 Add snapshot testing for cached doctrees

[chrisjsewell]

This adds some snapshot testing for cached doctrees of a sphinx build, with the snapshot_doctree fixture.

(only one has been added currently, as proof of principle, more can be added in the future)

[danwos]

Like the idea to test the doctree via snapshots as well.
But I'm not sure how stable a doctree is between different Sphinx/docutils versions, so this may affect the matrix build in future.

I see also two magic names, which should be documented somehow:

1. The file name of the snapshot, e.g. it contains test_functtion_name and test_app0.
   So the snapshot-file selection is done based on this, we should document this somewhere.

2. <document source="<source>"> in the snapshot.
   source seems to be set by hand to <source>, right?
   So this is a manual action we need to do for all new doctree-snapshots. This we should document as well, as the current docs tell us with pytest tests/ --snapshot-update all magic is done :)

[chrisjsewell]

But I'm not sure how stable a doctree is between different Sphinx/docutils versions, so this may affect the matrix build in future.

Tests in sphinx-design are based pretty much purely on doctree snapshots 😄: https://github.com/executablebooks/sphinx-design/blob/main/tests/test_snippets,
as are a lot of the tests in https://github.com/executablebooks/MyST-Parser,
so I have a lot of experience here

The file name of the snapshot, e.g. it contains test_function_name and test_app0.
So the snapshot-file selection is done based on this, we should document this somewhere.

Yep I can mention it in the documentation, although this is just the standard functioning of https://github.com/tophat/syrupy, and there is already a link to their documentation.

<document source="<source>"> in the snapshot. source seems to be set by hand to <source>, right?
So this is a manual action we need to do for all new doctree-snapshots.

No, its part of the test fixture, so it gets done automatically for snapshot_doctree (see the additions in tests/conftest.py)

[danwos]

Ahh ok, so it's much easier than I thought. Thanks for the details.