Document private protocol methods for devsite (#3440)

Fixes #2953.

Also adds a preview Dockerfile that is a seed for a potential preview service that could run as a GithubAction, deploy an ephemeral Cloud Run container to preview the generated docs and comment on the PR with the link. An example link for this particular change is: https://api-docs-fijpqdu4wa-uc.a.run.app/

While the preview is not "the real thing" - a fullblown devsite preview is not realistic at this point. This preview gives an indication about the intermediate markdown representation generated by tf-docs markdown generator. It's good for:
- latex checking in docstrings - e.g. https://api-docs-fijpqdu4wa-uc.a.run.app/cirq/experiments/two_qubit_state_tomography.md
- checking whether the private methods really show up: https://api-docs-fijpqdu4wa-uc.a.run.app/cirq/protocols/SupportsActOn.md

Author: balopat

.gitignore

@@ -23,6 +23,9 @@ __pycache__
 _build
 rtd_docs/generated
 
+# API docs
+docs/api_docs
+
 # swap files
 *.swp
 

check/nbformat

@@ -29,7 +29,7 @@ cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 cd "$(git rev-parse --show-toplevel)"
 
 # Install a pinned version of tf-docs
-TF_DOCS_COMMIT=ec2bfadbec885fc40268b4193d8b87648ab45791
+TF_DOCS_COMMIT=b3dc8a922d8bdc6e998a8ad4f4953359dc6e576a
 TF_DOCS_INSTALLED=$(pip list | grep  -c $TF_DOCS_COMMIT)
 
 if [ "$TF_DOCS_INSTALLED" != "1" ]; then

cirq/_doc.py

@@ -54,3 +54,33 @@ def document(value: Any, doc_string: str = ''):
         # print(traceback.format_stack(limit=2)[0])
         pass
     return value
+
+
+# This is based on
+# https://github.com/tensorflow/docs/commit/129e54b1a1dc2c2c82ad94bc81e986c7c2be3d6a#diff-85111596b523b2940651a8856939755c8531d470948895c7133deb6a537bc889R295-R324
+
+_DOC_PRIVATE = "_tf_docs_doc_private"
+
+
+def doc_private(obj):
+    """A decorator: Generates docs for private methods/functions.
+
+    For example:
+    ```
+    class Try:
+      @doc_private
+      def _private(self):
+        ...
+    ```
+    As a rule of thumb, private (beginning with `_`) methods/functions are
+    not documented. This decorator allows to force document a private
+    method/function.
+
+    Args:
+      obj: The class-attribute to force the documentation for.
+    Returns:
+      obj
+    """
+
+    setattr(obj, _DOC_PRIVATE, None)
+    return obj

cirq/experiments/qubit_characterizations.py

@@ -445,34 +445,26 @@ def two_qubit_state_tomography(sampler: work.Sampler,
     The state probabilities $P_{00}, P_{01}, P_{10}$ thus obtained contribute
     to the following linear equations (setting $c_{00} = 1$):
 
-        $$
-        c_{03} + c_{30} + c_{33} = 4*P_{00} - 1
-        $$
-
-        $$
-        -c_{03} + c_{30} - c_{33} = 4*P_{01} - 1
-        $$
-
-        $$
-        c_{03} - c_{30} - c_{33} = 4*P_{10} - 1
-        $$
+    $$
+    \begin{align}
+    c_{03} + c_{30} + c_{33} &= 4*P_{00} - 1 \\
+    -c_{03} + c_{30} - c_{33} &= 4*P_{01} - 1 \\
+    c_{03} - c_{30} - c_{33} &= 4*P_{10} - 1
+    \end{align}
+    $$
 
     And if a Y/2 rotation is applied to the first qubit and a X/2 rotation
     is applied to the second qubit before measurement, the measurement
     operators are $(I -/+ \sigma_x) \bigotimes (I +/- \sigma_y)$. The
     probabilities obtained instead contribute to the following linear equations:
 
-        $$
-        c_{02} - c_{10} - c_{12} = 4*P_{00} - 1
-        $$
-
-        $$
-        -c_{02} - c_{10} + c_{12} = 4*P_{01} - 1
-        $$
-
-        $$
-        c_{02} + c_{10} + c_{12} = 4*P_{10} - 1
-        $$
+    $$
+    \begin{align}
+    c_{02} - c_{10} - c_{12} &= 4*P_{00} - 1 \\
+    -c_{02} - c_{10} + c_{12} &= 4*P_{01} - 1 \\
+    c_{02} + c_{10} + c_{12} &= 4*P_{10} - 1
+    \end{align}
+    $$
 
     Note that this set of equations has the same form as the first set under
     the transformation $c_{03}$ <-> $c_{02}, c_{30}$ <-> $-c_{10}$ and

cirq/protocols/act_on_protocol.py

@@ -17,7 +17,7 @@
 
 from typing_extensions import Protocol
 
-from cirq._doc import document
+from cirq._doc import doc_private
 from cirq.type_workarounds import NotImplementedType
 
 if TYPE_CHECKING:
@@ -27,7 +27,7 @@
 class SupportsActOn(Protocol):
     """An object that explicitly specifies how to act on simulator states."""
 
-    @document
+    @doc_private
     def _act_on_(self, args: Any) -> Union[NotImplementedType, bool]:
         """Applies an action to the given argument, if it is a supported type.
 

cirq/protocols/apply_channel_protocol.py

@@ -19,6 +19,7 @@
 from typing_extensions import Protocol
 
 from cirq import linalg
+from cirq._doc import doc_private
 from cirq.protocols.apply_unitary_protocol import (
     apply_unitary,
     ApplyUnitaryArgs,
@@ -115,6 +116,7 @@ def __init__(self, target_tensor: np.ndarray, out_buffer: np.ndarray,
 class SupportsApplyChannel(Protocol):
     """An object that can efficiently implement a channel."""
 
+    @doc_private
     def _apply_channel_(self, args: ApplyChannelArgs
                        ) -> Union[np.ndarray, None, NotImplementedType]:
         """Efficiently applies a channel.

cirq/protocols/apply_mixture_protocol.py

@@ -19,6 +19,7 @@
 from typing_extensions import Protocol
 
 from cirq import linalg
+from cirq._doc import doc_private
 from cirq.protocols.apply_unitary_protocol import (
     apply_unitary,
     ApplyUnitaryArgs,
@@ -112,6 +113,7 @@ def __init__(self,
 class SupportsApplyMixture(Protocol):
     """An object that can efficiently implement a mixture."""
 
+    @doc_private
     def _apply_mixture_(self, args: ApplyMixtureArgs
                        ) -> Union[np.ndarray, None, NotImplementedType]:
         """Efficiently applies a mixture.

cirq/protocols/apply_unitary_protocol.py

@@ -29,6 +29,7 @@
 from typing_extensions import Protocol
 
 from cirq import linalg, qis
+from cirq._doc import doc_private
 from cirq.protocols import qid_shape_protocol
 from cirq.protocols.decompose_protocol import (
     _try_decompose_into_operations_and_qubits,)
@@ -219,6 +220,7 @@ def subspace_index(self,
 class SupportsConsistentApplyUnitary(Protocol):
     """An object that can be efficiently left-multiplied into tensors."""
 
+    @doc_private
     def _apply_unitary_(self, args: ApplyUnitaryArgs
                        ) -> Union[np.ndarray, None, NotImplementedType]:
         """Left-multiplies a unitary effect onto a tensor with good performance.

cirq/protocols/approximate_equality_protocol.py

@@ -22,10 +22,13 @@
 
 from typing_extensions import Protocol
 
+from cirq._doc import doc_private
+
 
 class SupportsApproximateEquality(Protocol):
     """Object which can be compared approximately."""
 
+    @doc_private
     def _approx_eq_(self, other: Any, *, atol: Union[int, float]) -> bool:
         """Approximate comparator.
 

cirq/protocols/channel.py

@@ -20,6 +20,7 @@
 import numpy as np
 from typing_extensions import Protocol
 
+from cirq._doc import doc_private
 from cirq.protocols.decompose_protocol import (
     _try_decompose_into_operations_and_qubits,)
 from cirq.protocols.mixture_protocol import has_mixture
@@ -42,6 +43,7 @@
 class SupportsChannel(Protocol):
     """An object that may be describable as a quantum channel."""
 
+    @doc_private
     def _channel_(self) -> Union[Sequence[np.ndarray], NotImplementedType]:
         r"""A list of matrices describing the quantum channel.
 
@@ -76,6 +78,8 @@ def _channel_(self) -> Union[Sequence[np.ndarray], NotImplementedType]:
             A list of matrices describing the channel (Kraus operators), or
             NotImplemented if there is no such matrix.
         """
+
+    @doc_private
     def _has_channel_(self) -> bool:
         """Whether this value has a channel representation.
 

cirq/protocols/circuit_diagram_info_protocol.py

@@ -21,6 +21,7 @@
 from typing_extensions import Protocol
 
 from cirq import protocols, value
+from cirq._doc import doc_private
 
 if TYPE_CHECKING:
     import cirq
@@ -304,6 +305,7 @@ def with_args(self, **kwargs):
 class SupportsCircuitDiagramInfo(Protocol):
     """A diagrammable operation on qubits."""
 
+    @doc_private
     def _circuit_diagram_info_(
             self, args: CircuitDiagramInfoArgs
     ) -> Union[str, Iterable[str], CircuitDiagramInfo]:

cirq/protocols/commutes_protocol.py

@@ -16,11 +16,10 @@
 from typing import Any, TypeVar, Union
 
 import numpy as np
-
 from typing_extensions import Protocol
 
 from cirq import linalg, ops
-from cirq._doc import document
+from cirq._doc import doc_private
 from cirq.protocols import qid_shape_protocol, unitary_protocol
 from cirq.type_workarounds import NotImplementedType
 
@@ -36,7 +35,7 @@
 class SupportsCommutes(Protocol):
     """An object that can determine commutation relationships vs others."""
 
-    @document
+    @doc_private
     def _commutes_(self, other: Any,
                    atol: float) -> Union[None, bool, NotImplementedType]:
         r"""Determines if this object commutes with the other object.

cirq/protocols/decompose_protocol.py

@@ -27,9 +27,11 @@
     Union,
 )
 from collections import defaultdict
+
 from typing_extensions import Protocol
 
 from cirq import devices, ops
+from cirq._doc import doc_private
 from cirq.protocols import qid_shape_protocol
 from cirq.type_workarounds import NotImplementedType
 
@@ -92,6 +94,7 @@ class SupportsDecompose(Protocol):
     raise a caller-provided error.
     """
 
+    @doc_private
     def _decompose_(self) -> DecomposeResult:
         pass
 

cirq/protocols/equal_up_to_global_phase_protocol.py

@@ -12,21 +12,22 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from collections.abc import Iterable
 import numbers
+from collections.abc import Iterable
 from typing import Any, Union
+
 import numpy as np
 from typing_extensions import Protocol
 
 from cirq import linalg
-from cirq._doc import document
+from cirq._doc import doc_private
 from cirq.protocols.approximate_equality_protocol import approx_eq
 
 
 class SupportsEqualUpToGlobalPhase(Protocol):
     """Object which can be compared for equality mod global phase."""
 
-    @document
+    @doc_private
     def _equal_up_to_global_phase_(self, other: Any, *,
                                    atol: Union[int, float]) -> bool:
         """Approximate comparator.

cirq/protocols/has_unitary_protocol.py

@@ -13,7 +13,6 @@
 # limitations under the License.
 
 from typing import (
-    TYPE_CHECKING,
     Any,
     TypeVar,
     Optional,
@@ -22,23 +21,20 @@
 import numpy as np
 from typing_extensions import Protocol
 
-from cirq._doc import document
+from cirq import qis
+from cirq._doc import doc_private
 from cirq.protocols import qid_shape_protocol
 from cirq.protocols.apply_unitary_protocol import ApplyUnitaryArgs
 from cirq.protocols.decompose_protocol import (
     _try_decompose_into_operations_and_qubits,)
-from cirq import qis
-
-if TYPE_CHECKING:
-    import cirq
 
 TDefault = TypeVar('TDefault')
 
 
 class SupportsExplicitHasUnitary(Protocol):
     """An object that explicitly specifies whether it has a unitary effect."""
 
-    @document
+    @doc_private
     def _has_unitary_(self) -> bool:
         """Determines whether the receiver has a unitary effect.
 

cirq/protocols/json_serialization.py

@@ -35,6 +35,7 @@
 import sympy
 from typing_extensions import Protocol
 
+from cirq._doc import doc_private
 from cirq.ops import raw_types  # Tells mypy that the raw_types module exists
 from cirq.type_workarounds import NotImplementedType
 
@@ -245,6 +246,7 @@ class SupportsJSON(Protocol):
     constructor.
     """
 
+    @doc_private
     def _json_dict_(self) -> Union[None, NotImplementedType, Dict[Any, Any]]:
         pass
 

cirq/protocols/measurement_key_protocol.py

@@ -17,12 +17,10 @@
 
 from typing_extensions import Protocol
 
-from cirq._doc import document
-
+from cirq._doc import doc_private
 from cirq.protocols.decompose_protocol import \
     _try_decompose_into_operations_and_qubits
 
-
 # This is a special indicator value used by the inverse method to determine
 # whether or not the caller provided a 'default' argument.
 RaiseTypeErrorIfNotProvided = ([],)  # type: Any
@@ -49,7 +47,7 @@ class SupportsMeasurementKey(Protocol):
     conditional on the measurement outcome being $k$.
     """
 
-    @document
+    @doc_private
     def _measurement_key_(self) -> str:
         """Return the key that will be used to identify this measurement.
 
@@ -58,7 +56,7 @@ def _measurement_key_(self) -> str:
         will be stored.
         """
 
-    @document
+    @doc_private
     def _measurement_keys_(self) -> Iterable[str]:
         """Return the keys for measurements performed by the receiving object.