Merge 'docs' branch into 'master'

[lamberta]

Mostly file moves and renames. Some Markdown fixes.

Some Sphinx-specific files moved into dev_tools/docs/sphinx/ —just in case you need them and can probably delete from repo when you are ready.

[lamberta]

Hmm. When I run pytest locally I get (tested on macOS):

=== test session starts ===
platform darwin -- Python 3.7.7, pytest-6.0.1, py-1.9.0, pluggy-0.13.1
rootdir: /Users/$USER/src/quantum/ReCirq
collected 325 items

recirq/documentation_utils_test.py .                                                                                                                                              [  0%]
recirq/engine_utils_test.py .........                                                                                                                                             [  3%]
recirq/serialization_utils_test.py .....                                                                                                                                          [  4%]
recirq/optimize/mgd_test.py ....                                                                                                                                                  [  5%]
recirq/optimize/minimize_test.py .                                                                                                                                                [  6%]
recirq/optimize/mpg_test.py .....                                                                                                                                                 [  7%]
recirq/qaoa/circuit_structure_test.py ........                                                                                                                                    [ 10%]
recirq/qaoa/classical_angle_optimization_test.py ..                                                                                                                               [ 10%]
recirq/qaoa/gates_and_compilation_test.py ...............s.s.........                                                                                                             [ 19%]
recirq/qaoa/placement_test.py ......................                                                                                                                              [ 25%]
recirq/qaoa/problem_circuits_test.py ...                                                                                                                                          [ 26%]
recirq/qaoa/problems_test.py .........                                                                                                                                            [ 29%]
recirq/qaoa/simulation_test.py .....                                                                                                                                              [ 31%]
recirq/quantum_chess/bit_utils_test.py .......                                                                                                                                    [ 33%]
recirq/quantum_chess/circuit_transformer_test.py ............                                                                                                                     [ 36%]
recirq/quantum_chess/controlled_iswap_test.py ....                                                                                                                                [ 38%]
recirq/quantum_chess/move_test.py .                                                                                                                                               [ 38%]
recirq/quantum_chess/puzzles_test.py ..................................................................................                                                           [ 63%]
recirq/quantum_chess/quantum_board_test.py ....................................................................................................................                   [ 99%]
recirq/quantum_chess/quantum_moves_test.py ..                                                                                                                                     [100%]

=== warnings summary ===
/Users/$USER/Library/Python/3.7/lib/python/site-packages/google/protobuf/descriptor.py:47
  /Users/$USER/Library/Python/3.7/lib/python/site-packages/google/protobuf/descriptor.py:47: DeprecationWarning: Using or importing the ABCs from 'collections' instead of from 'collections.abc' is deprecated since Python 3.3,and in 3.9 it will stop working
    from google.protobuf.pyext import _message

-- Docs: https://docs.pytest.org/en/stable/warnings.html
=== 323 passed, 2 skipped, 1 warning in 146.54s (0:02:26) ===

[mpharrigan]

One of the test failures is in a relatively new addition #48 and might be a flaky test. I'll investigate. The other failure is it's failing to build the documentation in the old way. I can disable this. Is there an easy command I can put into GitHub actions to verify that the docs build as part of the pre-submit checks?

[lamberta]

Is there an easy command I can put into GitHub actions to verify that the docs build as part of the pre-submit checks?

For notebooks used for narrative guides and tutorials, we use nbfmt to verify it's a valid notebook and formatted consistently to make the diffs easier to read. See: https://github.com/tensorflow/docs/tree/master/tools/tensorflow_docs/tools

And here's our GitHub Actions CI: https://github.com/tensorflow/docs/blob/master/.github/workflows/ci.yaml (also added an auto-format bot but that requires extra permissions).

The notebook content is tested post-submit (nightly if changed) when we import and run them. We'll send you an email notification if we detect a breakage (but if notebook outputs are saved, they won't be run). I'd imagine quota would be an issue if you wanted to execute the notebook within GitHub Actions, especially for long-running notebooks.

I don't think ReCirq has an API reference section, yes?
If it does (or you want to set that up for another package, could use the project's API docgen script (though I don't think it's been used as CI and not sure if the error handling is set up for it. Can investigate if this is something you want to look at):

# Install the tensorflow-docs package for the API generator
$ python3 -m pip install -U --user git+https://github.com/tensorflow/docs

# Generate Markdown from docstrings:
$ python3 dev_tools/docs/build_api_docs.py --output_dir=docs/api_docs

[mpharrigan]

• docs/development.md → development.md; it looks like this file managed to get copied from Cirq and ended up in the docs/ directory unmodified. Can we remove it, since none of it is applicable to ReCirq after a brief skim. Otherwise I can do this in a follow-up PR since it's obviously not your fault!

[mpharrigan]

I was able to build the staging site. This looks good from my end, although there are some general doc improvements that need to happen after this is merged. I'll open follow-up issues.

I'll submit a PR to disable the current doc-building stage of the CI so we can get a green checkmark, then open an issue to add an nbfmt check

[lamberta]

SG. Thanks! Once this lands, I might have some PRs for formatting and other docs fixes, but I'll submit those later.

[mpharrigan]

Can you merge master or rebase to pull in the changes to the CI from #55 ?

[lamberta]

@mpharrigan done!

[mpharrigan]

Thanks!