[qpolish] dev-site & readthedocs hybrid (#3227)

Adds a hybrid solution for devsite and readthedocs. 

Adds a hybrid solution where now the `docs` folder is the source of truth for devsite, our new documentation platform that will go live in a couple of months. This contains the current version of the `docs-site` branch. 

ReadTheDocs specific files now live in `rtd-docs` that should be rarely (if ever) modified. 
After spending a day on researching possible ways to do this I settled with a simple "copy" approach and re-referencing the "new docs" structure from the ReadTheDocs rst files. 

This will make some maintenance tasks like restructuring ReadTheDocs a bit tricky, but the situation is temporary and regular docs updates should be okay. 

* Docs site setup (#3085)
* Move examples index into tutorials/
* Move basics tutorial into tutorials/
* Add _index.yaml for site
* Add initial _book.yaml for leftnav

Co-authored-by: Matthew Harrigan <mpharrigan@google.com>
Co-authored-by: Animesh Sinha <AnimeshSinha1309@gmail.com>
Co-authored-by: Matthew Neeley <maffoo@google.com>
Co-authored-by: Dave Bacon <dabacon@gmail.com>
Co-authored-by: Matteo Pompili <matpompili@gmail.com>
Co-authored-by: MichaelBroughton <MichaelBroughton@users.noreply.github.com>

.github/workflows/ci.yml

@@ -119,7 +119,7 @@ jobs:
           pip install -r dev_tools/conf/pip-list-dev-tools.txt
           sudo apt-get install pandoc
       - name: Build docs
-        run: dev_tools/build-docs.sh
+        run: dev_tools/docs/build-rtd-docs.sh
   build_protos:
     name: Build protos
     runs-on: ubuntu-16.04

.gitignore

@@ -4,6 +4,7 @@ __pycache__
 
 # ignore idea SDK
 .idea/*
+.vscode
 
 # ignore cache
 .cache/*
@@ -20,7 +21,7 @@ __pycache__
 
 # Sphinx
 _build
-docs/generated
+rtd_docs/generated
 
 # swap files
 *.swp

.readthedocs.yml

@@ -1,8 +1,11 @@
+version: 2
 build:
   image: latest
 python:
   version: 3.6
-  pip_install: true
-  extra_requirements:
-      - contrib
-      - dev_env
+  install:
+      - requirements: requirements.txt
+      - requirements: dev_tools/conf/pip-list-dev-tools.txt
+      - requirements: cirq/contrib/contrib-requirements.txt
+sphinx:
+  configuration: rtd_docs/conf.py

README.rst

@@ -1,4 +1,4 @@
-.. image:: https://raw.githubusercontent.com/quantumlib/Cirq/master/docs/_static/Cirq_logo_color.png
+.. image:: https://raw.githubusercontent.com/quantumlib/Cirq/master/docs/images/Cirq_logo_color.png
   :target: https://github.com/quantumlib/cirq
   :alt: Cirq
   :width: 500px

check/doctest

@@ -17,4 +17,4 @@
 cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 cd "$(git rev-parse --show-toplevel)"
 
-PYTHONPATH="$(pwd)" python dev_tools/run_doctest.py $@
+PYTHONPATH="$(pwd)" python dev_tools/docs/run_doctest.py $@

check/pytest-changed-files

@@ -63,7 +63,7 @@ changed=$(git diff --name-only ${rev} -- \
 )
 if git diff --name-only "${rev}" -- | grep "__init__\.py$" > /dev/null; then
   # Include global API tests when an __init__ file is touched.
-  changed+=('docs/docs_coverage_test.py')
+  changed+=('rtd_docs/docs_coverage_test.py')
   changed+=('cirq/protocols/json_serialization_test.py')
 fi
 num_changed=$(echo -e "${changed[@]}" | wc -w)

check/pytest-changed-files-and-incremental-coverage

@@ -76,7 +76,7 @@ changed_python_tests=$(git diff --name-only "${rev}" -- \
 )
 if git diff --name-only "${rev}" -- | grep "__init__\.py$" > /dev/null; then
   # Include global API tests when an __init__ file is touched.
-  changed_python_tests+=('docs/docs_coverage_test.py')
+  changed_python_tests+=('rtd_docs/docs_coverage_test.py')
   changed_python_tests+=('cirq/protocols/json_serialization_test.py')
 fi
 if [ "${#changed_python_tests[@]}" -eq 0 ]; then

dev_tools/bash_scripts_test.py

@@ -151,7 +151,7 @@ def test_pytest_changed_files_file_selection(tmpdir_factory):
                  'git commit -m test --quiet --no-gpg-sign\n'
                  'echo x > __init__.py\n')
     assert result.exit_code == 0
-    assert result.out == ('INTERCEPTED pytest docs/docs_coverage_test.py '
+    assert result.out == ('INTERCEPTED pytest rtd_docs/docs_coverage_test.py '
                           'cirq/protocols/json_serialization_test.py\n')
     assert result.err.split() == (
         "Comparing against revision 'HEAD'.\n"

dev_tools/build-docs.sh → dev_tools/docs/build-rtd-docs.sh

@@ -17,25 +17,24 @@
 ################################################################################
 # Generates a local copy of Cirq's documentation, using Sphinx.
 #
-# Output currently goes into [REPO_ROOT]/docs/_build
+# Output currently goes into [REPO_ROOT]/rtd_docs/_build
 #
 # Temporary files generated by Sphinx (e.g. by the Napoleon extension
 # translating google-style docstrings) are put into [REPO_ROOT]/docs/generated,
 # which is cleared before and after this command runs.
 #
 # Usage:
-#     dev_tools/build-docs.sh
+#     dev_tools/docs/build-rtd-docs.sh
 ################################################################################
 
 set -e
 trap "{ echo -e '\033[31mFAILED\033[0m'; }" ERR
 
 # Get the working directory to the repo root.
-cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-cd "$(git rev-parse --show-toplevel)"
+cd "$(git rev-parse --show-toplevel)"/rtd_docs
 
-docs_conf_dir="docs"
-out_dir="docs/_build"
+docs_conf_dir="."
+out_dir="${docs_conf_dir}/_build"
 
 # Cleanup pre-existing temporary generated files.
 rm -rf "${docs_conf_dir}/generated"

docs/snippets_test.py → dev_tools/snippets_test.py

@@ -68,8 +68,7 @@
 
 def test_can_run_readme_code_snippets():
     # Get the contents of the README.md file at the project root.
-    readme_path = os.path.join(
-        os.path.split(os.path.dirname(__file__))[0], 'README.rst')
+    readme_path = 'README.rst'
     assert readme_path is not None
 
     assert_file_has_working_code_snippets(readme_path, assume_import=False)
@@ -121,6 +120,7 @@ def apply_overrides(content: str, overrides: List[Tuple[Pattern, str]]) -> str:
         override_content = re.sub(pattern, sub, override_content)
     return override_content
 
+
 def deindent_snippet(snippet: str) -> str:
     deindented_lines = []
     indentation_amount = None
@@ -151,10 +151,8 @@ def find_rst_test_overrides(content: str) -> List[Tuple[Pattern, str]]:
     test_sub_text = find_code_snippets(
         r'.. test-substitution::\n(([^\n]*\n){2})', content)
     substitutions = [line.split('\n')[:-1] for line, _ in test_sub_text]
-    return [
-        (re.compile(match.lstrip()), sub.lstrip())
-        for match, sub in substitutions
-    ]
+    return [(re.compile(match.lstrip()), sub.lstrip())
+            for match, sub in substitutions]
 
 
 def test_find_rst_code_snippets():
@@ -449,16 +447,14 @@ def test_canonicalize_printed_line():
     b = '[-0.5-0. j  0. -0.5j  0. -0.5j -0.5+0. j]'
     assert canonicalize_printed_line(a) == canonicalize_printed_line(b)
 
-    assert len({canonicalize_printed_line(e)
-                for e in ['[2.2]',
-                          '[+2.2]',
-                          '[ 2.2]']}) == 1
+    assert len({
+        canonicalize_printed_line(e) for e in ['[2.2]', '[+2.2]', '[ 2.2]']
+    }) == 1
 
-    assert len({canonicalize_printed_line(e)
-                for e in ['[-0.]',
-                          '[+0.]',
-                          '[ 0.]',
-                          '[0.]']}) == 1
+    assert len({
+        canonicalize_printed_line(e)
+        for e in ['[-0.]', '[+0.]', '[ 0.]', '[0.]']
+    }) == 1
 
     a = '[[ 0.+0.j 1.+0.j]'
     b = '[[0.+0.j 1.+0.j]'
@@ -487,6 +483,7 @@ def assert_code_snippet_executes_correctly(snippet: str,
         assert after is not None
         assert_code_snippet_fails(after, state, expected_failure)
 
+
 def assert_code_snippet_runs_and_prints_expected(snippet: str,
                                                  state: Dict,
                                                  line_number: int = None):
@@ -510,8 +507,7 @@ def print_capture(*values, sep=' '):
         raise
 
 
-def assert_code_snippet_fails(snippet: str,
-                              state: Dict,
+def assert_code_snippet_fails(snippet: str, state: Dict,
                               expected_failure_type: str):
     try:
         exec(snippet, state)
@@ -520,8 +516,7 @@ def assert_code_snippet_fails(snippet: str,
         if expected_failure_type not in actual_failure_types:
             raise AssertionError(
                 'Expected snippet to raise a {}, but it raised a {}.'.format(
-                    expected_failure_type,
-                    ' -> '.join(actual_failure_types)))
+                    expected_failure_type, ' -> '.join(actual_failure_types)))
         return
 
     raise AssertionError('Expected snippet to fail, but it ran to completion.')
@@ -553,13 +548,11 @@ def assert_expected_lines_present_in_order(expected_lines: List[str],
             'Highlighted Differences:\n'
             '{}\n'
             ''.format(
-                expected,
-                _indent(actual_lines),
-                _indent(expected_lines),
-                _indent([cirq.testing.highlight_text_differences(
-                    '\n'.join(actual_lines),
-                    '\n'.join(expected_lines))]))
-        )
+                expected, _indent(actual_lines), _indent(expected_lines),
+                _indent([
+                    cirq.testing.highlight_text_differences(
+                        '\n'.join(actual_lines), '\n'.join(expected_lines))
+                ])))
         i += 1
 
 
@@ -665,43 +658,34 @@ def test_find_expected_outputs():
 
 
 def test_assert_expected_lines_present_in_order():
-    assert_expected_lines_present_in_order(
-        expected_lines=[],
-        actual_lines=[])
+    assert_expected_lines_present_in_order(expected_lines=[], actual_lines=[])
 
-    assert_expected_lines_present_in_order(
-        expected_lines=[],
-        actual_lines=['abc'])
+    assert_expected_lines_present_in_order(expected_lines=[],
+                                           actual_lines=['abc'])
 
-    assert_expected_lines_present_in_order(
-        expected_lines=['abc'],
-        actual_lines=['abc'])
+    assert_expected_lines_present_in_order(expected_lines=['abc'],
+                                           actual_lines=['abc'])
 
     with pytest.raises(AssertionError):
-        assert_expected_lines_present_in_order(
-            expected_lines=['abc'],
-            actual_lines=[])
+        assert_expected_lines_present_in_order(expected_lines=['abc'],
+                                               actual_lines=[])
 
-    assert_expected_lines_present_in_order(
-        expected_lines=['abc', 'def'],
-        actual_lines=['abc', 'def'])
+    assert_expected_lines_present_in_order(expected_lines=['abc', 'def'],
+                                           actual_lines=['abc', 'def'])
 
     assert_expected_lines_present_in_order(
         expected_lines=['abc', 'def'],
         actual_lines=['abc', 'interruption', 'def'])
 
     with pytest.raises(AssertionError):
-        assert_expected_lines_present_in_order(
-            expected_lines=['abc', 'def'],
-            actual_lines=['def', 'abc'])
+        assert_expected_lines_present_in_order(expected_lines=['abc', 'def'],
+                                               actual_lines=['def', 'abc'])
 
-    assert_expected_lines_present_in_order(
-        expected_lines=['abc    '],
-        actual_lines=['abc'])
+    assert_expected_lines_present_in_order(expected_lines=['abc    '],
+                                           actual_lines=['abc'])
 
-    assert_expected_lines_present_in_order(
-        expected_lines=['abc'],
-        actual_lines=['abc      '])
+    assert_expected_lines_present_in_order(expected_lines=['abc'],
+                                           actual_lines=['abc      '])
 
 
 def test_assert_code_snippet_executes_correctly():
@@ -718,31 +702,36 @@ def test_assert_code_snippet_executes_correctly():
     with pytest.raises(SyntaxError):
         assert_code_snippet_executes_correctly("a = ;", {})
 
-    assert_code_snippet_executes_correctly("""
+    assert_code_snippet_executes_correctly(
+        """
 print("abc")
 # prints
 # abc
         """, {})
 
     if sys.version_info[0] >= 3:  # Our print capture only works in python 3.
         with pytest.raises(AssertionError):
-            assert_code_snippet_executes_correctly("""
+            assert_code_snippet_executes_correctly(
+                """
 print("abc")
 # prints
 # def
                 """, {})
 
-    assert_code_snippet_executes_correctly("""
+    assert_code_snippet_executes_correctly(
+        """
 # raises ZeroDivisionError
 a = 1 / 0
     """, {})
 
-    assert_code_snippet_executes_correctly("""
+    assert_code_snippet_executes_correctly(
+        """
 # raises ArithmeticError
 a = 1 / 0
         """, {})
 
-    assert_code_snippet_executes_correctly("""
+    assert_code_snippet_executes_correctly(
+        """
 # prints 123
 print("123")
 
@@ -751,13 +740,15 @@ def test_assert_code_snippet_executes_correctly():
         """, {})
 
     with pytest.raises(AssertionError):
-        assert_code_snippet_executes_correctly("""
+        assert_code_snippet_executes_correctly(
+            """
 # raises ValueError
 a = 1 / 0
             """, {})
 
     with pytest.raises(AssertionError):
-        assert_code_snippet_executes_correctly("""
+        assert_code_snippet_executes_correctly(
+            """
 # raises
 a = 1
             """, {})