Fix snippets_test.py::test_can_run_docs_code_snippets

[pavoljuhas]

Describe the issue

Problem: Unit test snippets_test.py::test_can_run_docs_code_snippets is supposed to verify Python code snippets in markdown files under the docs directory, but it looks for them in the dev_tools directory instead. Markdown files in dev_tools have no snippets to check so the test is a no-op.

$ pytest --quiet --co dev_tools/snippets_test.py::test_can_run_docs_code_snippets
dev_tools/snippets_test.py::test_can_run_docs_code_snippets[cirq-infra/README.md]
dev_tools/snippets_test.py::test_can_run_docs_code_snippets[triage-party/README.md]
dev_tools/snippets_test.py::test_can_run_docs_code_snippets[ci/README.md]

At the time of its writing in #2307 the snippets_test.py was in the docs directory, but #3227 moved it to dev_tools without adjusting its markdown files search.

Solution: Fix markdown files search in snippets_test.py and fix any issues that pop out in the docs/**/*.md files (some snippets may need to be excluded if it is too much hassle to make them pass).

Tell us the version of Cirq where this happens

1.7.0.dev0 at 53b552cb7125d61112a76e725807eab7ef764170

[ToastCheng]

Hi @pavoljuhas! If no one has started, I can take this one.

[ToastCheng]

#7798 - changing the docs path. It now covers the md files under docs/.

After letting the test check the md files under docs/, there are mainly two types of error popping out:

1. undefined variable
2. Failed to import cirq_* (like cirq_google)

• For 1, I fixed the md snippet in #7798.
• For 2, I excluded md docs under hardware/ and google/ for now

[pavoljuhas]

After #7798 the snippet test covers 16 markdown doc files, up from 3 before. The files under docs/google and docs/hardware are for now excluded - as listed in the section below.

I'd like to address them in a follow-up PRs. Especially, the documents under docs/google have a test_substitution markup so at some point they were included and passing this test. Also as these are docs for our own hardware, we should have them up-to-date and tested.

The docs/google snippets should be fixable by assuming import cirq_google (as done for import cirq) for files in that directory and by tweaking or adding test_substitution markup as needed; for example some of the cloud-using calls could be replaced by a MagicMock() objects for the test. At the same time we need to check that those snippets are correct and in sync with the current APIs.

Also as a first step, any files that contain no snippets at all can be enabled right-away. That PR should change to exclusion rule to exclude individual files rather than directories.

TODO - files to revisit

Please check-mark files below that get included and test covered in later PRs. If some file is too tricky to test and we decide to skip it, please check as well and add a short comment why it is skipped.

• [ ] google/access.md
• [ ] google/calibration.md
• [ ] google/devices.md
• [ ] google/engine.md
• [ ] google/specification.md
• [ ] hardware/aqt/access.md
• [ ] hardware/azure-quantum/access.md
• [ ] hardware/ionq/access.md
• [ ] hardware/ionq/calibrations.md
• [ ] hardware/ionq/circuits.md
• [ ] hardware/ionq/jobs.md
• [ ] hardware/ionq/service.md
• [ ] hardware/pasqal/access.md
• [ ] hardware/pasqal/devices.md
• [ ] hardware/pasqal/sampler.md

[pavoljuhas]

@ToastCheng - thank you for contributing #7798! Would you be interested in taking up the follow-up work to extend test coverage for snippets that are currently excluded?

[ToastCheng]

Sure! I can try including the rest of the md files into the snippet test.

[ToastCheng]

Uploaded #7803 to address the docs/google part.