Add extensions to document public constants (#3367)

I need a Dictionary mapping from `int -> str`. The current way `int -> NamedTuple` which doesn't work for other projects.

cirq/_doc.py

@@ -13,19 +13,12 @@
 # limitations under the License.
 """Workaround for associating docstrings with public constants."""
 
-from typing import Any, Dict, NamedTuple, Optional
+from typing import Any, Dict
 
-DocProperties = NamedTuple(
-    'DocProperties',
-    [
-        ('doc_string', Optional[str]),
-    ],
-)
+RECORDED_CONST_DOCS: Dict[int, str] = {}
 
-RECORDED_CONST_DOCS: Dict[int, DocProperties] = {}
 
-
-def document(value: Any, doc_string: Optional[str] = None):
+def document(value: Any, doc_string: str = ''):
     """Stores documentation details about the given value.
 
     This method is used to associate a docstring with global constants. It is
@@ -43,8 +36,7 @@ def document(value: Any, doc_string: Optional[str] = None):
     Returns:
         The given value.
     """
-    docs = DocProperties(doc_string=doc_string)
-    RECORDED_CONST_DOCS[id(value)] = docs
+    RECORDED_CONST_DOCS[id(value)] = doc_string
 
     ## this is how the devsite API generator picks up
     ## docstrings for type aliases

dev_tools/docs/build_api_docs.py

@@ -23,6 +23,7 @@
 from tensorflow_docs.api_generator import public_api
 
 import cirq
+from cirq import _doc
 
 flags.DEFINE_string("output_dir", "/tmp/cirq_api", "Where to output the docs")
 
@@ -56,7 +57,9 @@ def main(unused_argv):
             "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)
 

rtd_docs/conf.py

@@ -101,11 +101,11 @@ def autodoc_skip_member(
 def autodoc_process(app, what: str, name: str, obj: Any, options,
                     lines: List[str]) -> None:
     # Try to lookup in documented dictionary.
-    found = _doc.RECORDED_CONST_DOCS.get(id(obj))
-    if name.startswith('cirq') and found is not None:
+    doc_string = _doc.RECORDED_CONST_DOCS.get(id(obj))
+    if name.startswith('cirq') and doc_string is not None:
         # Override docstring if requested.
-        if found.doc_string is not None:
-            new_doc_string = inspect.cleandoc(found.doc_string)
+        if doc_string is not None:
+            new_doc_string = inspect.cleandoc(doc_string)
             lines[:] = new_doc_string.split('\n')
     elif not (getattr(obj, '__module__', 'cirq') or '').startswith('cirq'):
         # Don't convert objects from other modules.