Repository: quantumlib/Cirq

Issue:
API reference for cirq.google is broken
**Description of the issue**

Objects under cirq.google are inaccessible currently since the v0.11 release.

**How to reproduce the issue**

E.g.: https://quantumai.google/reference/python/cirq/google/ConvertToXmonGates

**Cirq version**
v0.11 




Discussion:

Resolving patch:
diff --git a/dev_tools/docs/build_api_docs.py b/dev_tools/docs/build_api_docs.py
--- a/dev_tools/docs/build_api_docs.py
+++ b/dev_tools/docs/build_api_docs.py
@@ -14,10 +14,15 @@
 # ==============================================================================
 """Tool to generate external api_docs for Cirq.
 
-This version is for the stable docs building that uses the v0.10 monolithic cirq
-module. This will be replaced with build_api_docs_multi_module.py after v0.11 is
-released.
+In order to publish to our site, devsite runs two jobs for us: stable and nightly.
+The stable one downloads the latest cirq release from pypi and uses that to generate the reference
+API docs.
+The nightly one downloads the latest cirq pre-release (pip install cirq --pre) and uses that to
+generate the "nightly diff".
+
+This script needs to cater for both of these cases.
 """
+
 import os
 import types
 
@@ -29,19 +34,21 @@
 from tensorflow_docs.api_generator import public_api
 
 import cirq
+import cirq_google
+
 from cirq import _doc
 
-flags.DEFINE_string("output_dir", "/tmp/cirq_api", "Where to output the docs")
+flags.DEFINE_string("output_dir", "docs/api_docs", "Where to output the docs")
 
 flags.DEFINE_string(
     "code_url_prefix",
-    "https://github.com/quantumlib/cirq/tree/master/cirq",
+    "https://github.com/quantumlib/Cirq/blob/master",
     "The url prefix for links to code.",
 )
 
 flags.DEFINE_bool("search_hints", True, "Include metadata search hints in the generated files")
 
-flags.DEFINE_string("site_path", "quark/cirq/api_docs/python", "Path prefix in the _toc.yaml")
+flags.DEFINE_string("site_path", "reference/python", "Path prefix in the _toc.yaml")
 
 FLAGS = flags.FLAGS
 
@@ -64,20 +71,19 @@ def filter_unwanted_inherited_methods(path, parent, children):
 
 
 def main(unused_argv):
+    generate_cirq()
+    generate_cirq_google()
+
+
+def generate_cirq():
     doc_generator = generate_lib.DocGenerator(
         root_title="Cirq",
         py_modules=[("cirq", cirq)],
         base_dir=os.path.dirname(cirq.__file__),
-        code_url_prefix=FLAGS.code_url_prefix,
+        code_url_prefix=FLAGS.code_url_prefix + "/cirq-core/cirq",
         search_hints=FLAGS.search_hints,
         site_path=FLAGS.site_path,
         callbacks=[public_api.local_definitions_filter, filter_unwanted_inherited_methods],
-        private_map={
-            # Opt to not build docs for these paths for now since they error.
-            "cirq.google.engine.client.quantum.QuantumEngineServiceClient": ["enums"],
-            "cirq.google.engine.client.quantum_v1alpha1.QuantumEngineServiceClient": ["enums"],
-            "cirq.google.api": ["v1"],
-        },
         extra_docs=_doc.RECORDED_CONST_DOCS,
     )
     doc_controls.decorate_all_class_attributes(
@@ -86,5 +92,25 @@ def main(unused_argv):
     doc_generator.build(output_dir=FLAGS.output_dir)
 
 
+def generate_cirq_google():
+    doc_generator = generate_lib.DocGenerator(
+        root_title="Cirq-google",
+        py_modules=[("cirq_google", cirq_google)],
+        base_dir=os.path.dirname(cirq_google.__file__),
+        code_url_prefix=FLAGS.code_url_prefix + "/cirq-google/cirq_google",
+        search_hints=FLAGS.search_hints,
+        site_path=FLAGS.site_path,
+        callbacks=[public_api.local_definitions_filter, filter_unwanted_inherited_methods],
+        private_map={
+            # Opt to not build docs for these paths for now since they error.
+            "cirq_google.engine.client.quantum.QuantumEngineServiceClient": ["enums"],
+            "cirq_google.engine.client.quantum_v1alpha1.QuantumEngineServiceClient": ["enums"],
+            "cirq_google.api": ["v1"],
+        },
+        extra_docs=_doc.RECORDED_CONST_DOCS,
+    )
+    doc_generator.build(output_dir=FLAGS.output_dir)
+
+
 if __name__ == "__main__":
     app.run(main)
diff --git a/dev_tools/docs/build_api_docs_multi_module.py b/dev_tools/docs/build_api_docs_multi_module.py
deleted file mode 100644
--- a/dev_tools/docs/build_api_docs_multi_module.py
+++ /dev/null
@@ -1,109 +0,0 @@
-# Copyright 2020 The Cirq Authors. All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-# ==============================================================================
-"""Tool to generate external api_docs for Cirq.
-
-This version is for the nightly docs building that uses the new modules, cirq-core and cirq-google.
-"""
-
-import os
-import types
-
-import networkx
-from absl import app
-from absl import flags
-from tensorflow_docs.api_generator import doc_controls
-from tensorflow_docs.api_generator import generate_lib
-from tensorflow_docs.api_generator import public_api
-
-import cirq
-import cirq_google
-from cirq import _doc
-
-flags.DEFINE_string("output_dir", "/tmp/cirq_api", "Where to output the docs")
-
-flags.DEFINE_string(
-    "code_url_prefix",
-    "https://github.com/quantumlib/cirq/tree/master/cirq",
-    "The url prefix for links to code.",
-)
-
-flags.DEFINE_bool("search_hints", True, "Include metadata search hints in the generated files")
-
-flags.DEFINE_string("site_path", "reference/python", "Path prefix in the _toc.yaml")
-
-FLAGS = flags.FLAGS
-
-
-def filter_unwanted_inherited_methods(path, parent, children):
-    """Filter the unwanted inherited methods.
-
-    CircuitDag inherits a lot of methods from `networkx.DiGraph` and `Graph`.
-    This filter removes these, as it creates a lot of noise in the API docs.
-    """
-    if parent.__name__ != "CircuitDag":
-        return children
-
-    filtered_children = []
-    for name, obj in children:
-        if isinstance(obj, types.FunctionType):
-            if obj.__module__.startswith('cirq'):
-                filtered_children.append((name, obj))
-    return filtered_children
-
-
-def main(unused_argv):
-    generate_cirq()
-    generate_cirq_google()
-
-
-def generate_cirq():
-    doc_generator = generate_lib.DocGenerator(
-        root_title="Cirq",
-        py_modules=[("cirq", cirq)],
-        base_dir=os.path.dirname(cirq.__file__),
-        code_url_prefix=FLAGS.code_url_prefix,
-        search_hints=FLAGS.search_hints,
-        site_path=FLAGS.site_path,
-        callbacks=[public_api.local_definitions_filter, filter_unwanted_inherited_methods],
-        extra_docs=_doc.RECORDED_CONST_DOCS,
-    )
-    doc_controls.decorate_all_class_attributes(
-        doc_controls.do_not_doc_inheritable, networkx.DiGraph, skip=[]
-    )
-    doc_generator.build(output_dir=FLAGS.output_dir)
-
-
-def generate_cirq_google():
-    doc_generator = generate_lib.DocGenerator(
-        root_title="Cirq-google",
-        py_modules=[("cirq_google", cirq_google)],
-        base_dir=os.path.dirname(cirq_google.__file__),
-        code_url_prefix=FLAGS.code_url_prefix,
-        search_hints=FLAGS.search_hints,
-        site_path=FLAGS.site_path,
-        callbacks=[public_api.local_definitions_filter, filter_unwanted_inherited_methods],
-        private_map={
-            # Opt to not build docs for these paths for now since they error.
-            "cirq_google.engine.client.quantum.QuantumEngineServiceClient": ["enums"],
-            "cirq_google.engine.client.quantum_v1alpha1.QuantumEngineServiceClient": ["enums"],
-            "cirq_google.api": ["v1"],
-        },
-        extra_docs=_doc.RECORDED_CONST_DOCS,
-    )
-    doc_generator.build(output_dir=FLAGS.output_dir)
-
-
-if __name__ == "__main__":
-    app.run(main)


Test patch: