Fix remaining issues for v1.9 (#277)

- Fix doctests not being run by continuous integration
- Add a `doctest_proper.py` script for running doctests and actually including values added at import time
- Fix the doctest failures accumulated due to the fact that they weren't even being checked
- Rewrite `generate_api_reference.py` to have output more like the generated `stim.pyi` stubs file
- Add `stim.TableauSimulator.{h_xz,cx,zcx,zcy,zcz}` gate alias methods
- Add `stim.TableauSimulator.{c_xyz,c_zyx}` gate methods
- Add `stim.TableauSimulator.num_qubits`

Fixes #275

Author: Strilanc

.github/workflows/ci.yml

@@ -282,7 +282,7 @@ jobs:
       - run: pip install pybind11==2.9.2 && python setup.py install  # Workaround for https://github.com/pypa/setuptools/issues/230
       - run: pip install pytest
       - run: pytest src
-      - run: python -c "import stim; import doctest; assert doctest.testmod(stim).failed == 0"
+      - run: ./doctest_proper.py --module stim
   test_stimcirq:
     runs-on: ubuntu-latest
     steps:
@@ -296,7 +296,7 @@ jobs:
       - run: pip install -e glue/cirq
       - run: pip install pytest
       - run: pytest glue/cirq
-      - run: python -c "import stimcirq; import doctest; assert doctest.testmod(stimcirq).failed == 0"
+      - run: ./doctest_proper.py --module stimcirq --import cirq sympy
   test_sinter:
     runs-on: ubuntu-latest
     steps:
@@ -310,7 +310,7 @@ jobs:
       - run: pip install -e glue/sample
       - run: pip install pytest
       - run: pytest glue/sample
-      - run: python -c "import sinter; import doctest; assert doctest.testmod(sinter).failed == 0"
+      - run: ./doctest_proper.py --module sinter
   test_stimzx:
     runs-on: ubuntu-latest
     steps:
@@ -324,7 +324,7 @@ jobs:
       - run: pip install -e glue/zx
       - run: pip install pytest
       - run: pytest glue/zx
-      - run: python -c "import stimzx; import doctest; assert doctest.testmod(stimzx).failed == 0"
+      - run: ./doctest_proper.py --module stimzx
   test_stimjs:
     runs-on: ubuntu-latest
     steps:

doc/developer_documentation.md

@@ -40,7 +40,7 @@ These notes generally assume you are on a Linux system.
 - [autoformating code](#autoformat)
     - [with clang-format](#autoformat.clang-format)
 
-# <a name="compatibility></a>Compatibility guarantees across versions
+# <a name="compatibility"></a>Compatibility guarantees across versions
 
 A *bug* is bad behavior that wasn't intended. For example, the program crashing instead of returning empty results when sampling from an empty circuit would be a bug.
 
@@ -410,49 +410,52 @@ See [creating a python dev environment](#venv) for instructions on creating a
 python virtual environment with your changes to stim installed.
 
 Unit tests are run using `pytest`.
-Examples in docstrings are tested using `doctest`.
+Examples in docstrings are tested using the `doctest_proper` script at the repo root,
+which uses python's [`doctest`](https://docs.python.org/3/library/doctest.html) module
+but ensures values added to a module at import time are also tested (instead of requiring
+them to be [manually listed in a `__test__` property](https://docs.python.org/3/library/doctest.html#which-docstrings-are-examined)).
 
 To test everything:
 
 ```bash
 # from the repository root in a virtualenv with development wheels installed:
 pytest src glue
-python -c "import stim; import doctest; assert doctest.testmod(stim).failed == 0"
-python -c "import stimcirq; import doctest; assert doctest.testmod(stimcirq).failed == 0"
-python -c "import sinter; import doctest; assert doctest.testmod(sinter).failed == 0"
-python -c "import stimzx; import doctest; assert doctest.testmod(stimzx).failed == 0"
+./doctest_proper.py --module stim
+./doctest_proper.py --module stimcirq --import cirq sympy
+./doctest_proper.py --module sinter
+./doctest_proper.py --module stimzx
 ```
 
 Test only `stim`:
 
 ```bash
 # from the repository root in a virtualenv with development wheels installed:
 pytest src
-python -c "import stim; import doctest; assert doctest.testmod(stim).failed == 0"
+./doctest_proper.py --module stim
 ```
 
 Test only `stimcirq`:
 
 ```bash
 # from the repository root in a virtualenv with development wheels installed:
 pytest glue/cirq
-python -c "import stimcirq; import doctest; assert doctest.testmod(sitmcirq).failed == 0"
+./doctest_proper.py --module stimcirq --import cirq sympy
 ```
 
 Test only `sinter`:
 
 ```bash
 # from the repository root in a virtualenv with development wheels installed:
 pytest glue/sample
-python -c "import sinter; import doctest; assert doctest.testmod(sinter).failed == 0"
+./doctest_proper.py --module sinter
 ```
 
 Test only `stimzx`:
 
 ```bash
 # from the repository root in a virtualenv with development wheels installed:
 pytest glue/zx
-python -c "import stimzx; import doctest; assert doctest.testmod(stimzx).failed == 0"
+./doctest_proper.py --module stimzx
 ```