Merge pull request #17074 from lidizheng/python-doc-gen

The new gRPC Python documentation generator

10 files changed, 384 insertions, 70 deletions

diff --git a/doc/python/sphinx/api.rst b/doc/python/sphinx/api.rst
new file mode 100644
index 0000000000..425504fb28
--- /dev/null
+++ b/doc/python/sphinx/api.rst
@@ -0,0 +1,153 @@
+API Reference
+=============
+
+.. module:: grpc
+
+Create Client
+-------------
+
+.. autofunction:: insecure_channel
+.. autofunction:: secure_channel
+.. autofunction:: intercept_channel
+
+
+Create Client Credentials
+-------------------------
+
+.. autofunction:: ssl_channel_credentials
+.. autofunction:: metadata_call_credentials
+.. autofunction:: access_token_call_credentials
+.. autofunction:: composite_call_credentials
+.. autofunction:: composite_channel_credentials
+
+
+Create Server
+-------------
+
+.. autofunction:: server
+
+
+Create Server Credentials
+-------------------------
+
+.. autofunction:: ssl_server_credentials
+.. autofunction:: ssl_server_certificate_configuration
+.. autofunction:: dynamic_ssl_server_credentials
+
+
+RPC Method Handlers
+--------------------------
+
+.. autofunction:: unary_unary_rpc_method_handler
+.. autofunction:: unary_stream_rpc_method_handler
+.. autofunction:: stream_unary_rpc_method_handler
+.. autofunction:: stream_stream_rpc_method_handler
+.. autofunction:: method_handlers_generic_handler
+
+
+Channel Ready Future
+--------------------------
+
+.. autofunction:: channel_ready_future
+
+
+Channel Connectivity
+--------------------------
+
+.. autoclass:: ChannelConnectivity
+
+
+gRPC Status Code
+--------------------------
+
+.. autoclass:: StatusCode
+
+
+Channel Object
+--------------
+
+.. autoclass:: Channel
+
+
+Server Object
+-------------
+
+.. autoclass:: Server
+
+
+Authentication & Authorization Objects
+--------------------------------------
+
+.. autoclass:: ChannelCredentials
+.. autoclass:: CallCredentials
+.. autoclass:: AuthMetadataContext
+.. autoclass:: AuthMetadataPluginCallback
+.. autoclass:: AuthMetadataPlugin
+.. autoclass:: ServerCredentials
+.. autoclass:: ServerCertificateConfiguration
+
+
+gRPC Exceptions
+---------------
+
+.. autoexception:: RpcError
+
+
+Shared Context
+--------------
+
+.. autoclass:: RpcContext
+
+
+Client-Side Context
+-----------------------
+
+.. autoclass:: Call
+
+
+Client-Side Interceptor
+------------------------------------------------
+
+.. autoclass:: ClientCallDetails
+.. autoclass:: UnaryUnaryClientInterceptor
+.. autoclass:: UnaryStreamClientInterceptor
+.. autoclass:: StreamUnaryClientInterceptor
+.. autoclass:: StreamStreamClientInterceptor
+
+
+Service-Side Context
+--------------------
+
+.. autoclass:: ServicerContext
+
+
+Service-Side Handler
+-------------------------------
+
+.. autoclass:: RpcMethodHandler
+.. autoclass:: HandlerCallDetails
+.. autoclass:: GenericRpcHandler
+.. autoclass:: ServiceRpcHandler
+
+
+Service-Side Interceptor
+------------------------
+
+.. autoclass:: ServerInterceptor
+
+
+Multi-Callable
+-------------------------
+
+.. autoclass:: UnaryUnaryMultiCallable
+.. autoclass:: UnaryStreamMultiCallable
+.. autoclass:: StreamUnaryMultiCallable
+.. autoclass:: StreamStreamMultiCallable
+
+
+Future
+----------------
+
+.. autoexception:: FutureTimeoutError
+.. autoexception:: FutureCancelledError
+.. autoclass:: Future
diff --git a/doc/python/sphinx/conf.py b/doc/python/sphinx/conf.py
new file mode 100644
index 0000000000..1eb3a5de7f
--- /dev/null
+++ b/doc/python/sphinx/conf.py
@@ -0,0 +1,102 @@
+# Copyright 2018 The gRPC Authors
+#
+# 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.
+
+# -- Path setup --------------------------------------------------------------
+
+import os
+import sys
+PYTHON_FOLDER = os.path.join(os.path.dirname(os.path.realpath(__file__)),
+                             '..', '..', '..', 'src', 'python')
+sys.path.insert(0, os.path.join(PYTHON_FOLDER, 'grpcio'))
+sys.path.insert(0, os.path.join(PYTHON_FOLDER, 'grpcio_health_checking'))
+sys.path.insert(0, os.path.join(PYTHON_FOLDER, 'grpcio_reflection'))
+sys.path.insert(0, os.path.join(PYTHON_FOLDER, 'grpcio_testing'))
+
+# -- Project information -----------------------------------------------------
+
+project = 'gRPC Python'
+copyright = '2018, The gRPC Authors'
+author = 'The gRPC Authors'
+
+# Import generated grpc_version after the path been modified
+import grpc_version
+version = ".".join(grpc_version.VERSION.split(".")[:3])
+release = grpc_version.VERSION
+
+# -- General configuration ---------------------------------------------------
+
+templates_path = ['_templates']
+source_suffix = ['.rst', '.md']
+master_doc = 'index'
+language = 'en'
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+pygments_style = None
+
+# --- Extensions Configuration -----------------------------------------------
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.todo',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.coverage',
+]
+
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_special_with_doc = True
+
+autodoc_default_options = {
+    'members': None,
+}
+
+autodoc_mock_imports = [
+    'grpc._cython',
+    'grpc_health.v1.health_pb2',
+    'grpc_health.v1.health_pb2_grpc',
+    'grpc_reflection.v1alpha.reflection_pb2',
+    'grpc_reflection.v1alpha.reflection_pb2_grpc',
+]
+
+# -- HTML Configuration -------------------------------------------------
+
+html_theme = 'alabaster'
+html_theme_options = {
+    'fixed_sidebar': True,
+    'page_width': '1140px',
+    'show_related': True,
+    'analytics_id': 'UA-60127042-1',
+    'description': grpc_version.VERSION,
+    'show_powered_by': False,
+}
+
+# -- Options for manual page output ------------------------------------------
+
+man_pages = [(master_doc, 'grpcio', 'grpcio Documentation', [author], 1)]
+
+# -- Options for Texinfo output ----------------------------------------------
+
+texinfo_documents = [
+    (master_doc, 'grpcio', 'grpcio Documentation', author, 'grpcio',
+     'One line description of project.', 'Miscellaneous'),
+]
+
+# -- Options for Epub output -------------------------------------------------
+
+epub_title = project
+epub_exclude_files = ['search.html']
+
+# -- Options for todo extension ----------------------------------------------
+
+todo_include_todos = True
diff --git a/doc/python/sphinx/glossary.rst b/doc/python/sphinx/glossary.rst
new file mode 100644
index 0000000000..dee5d16143
--- /dev/null
+++ b/doc/python/sphinx/glossary.rst
@@ -0,0 +1,16 @@
+Glossary
+================
+
+.. glossary::
+
+  metadatum
+    A key-value pair included in the HTTP header.  It is a
+    2-tuple where the first entry is the key and the
+    second is the value, i.e. (key, value).  The metadata key is an ASCII str,
+    and must be a valid HTTP header name.  The metadata value can be
+    either a valid HTTP ASCII str, or bytes.  If bytes are provided,
+    the key must end with '-bin', i.e.
+    ``('binary-metadata-bin', b'\\x00\\xFF')``
+
+  metadata
+    A sequence of metadatum.
diff --git a/doc/python/sphinx/grpc_health_checking.rst b/doc/python/sphinx/grpc_health_checking.rst
new file mode 100644
index 0000000000..b344e34ac9
--- /dev/null
+++ b/doc/python/sphinx/grpc_health_checking.rst
@@ -0,0 +1,7 @@
+gRPC Health Checking
+====================
+
+Module Contents
+---------------
+
+.. autoclass:: grpc_health.v1.health.HealthServicer
diff --git a/doc/python/sphinx/grpc_reflection.rst b/doc/python/sphinx/grpc_reflection.rst
new file mode 100644
index 0000000000..043f2edb96
--- /dev/null
+++ b/doc/python/sphinx/grpc_reflection.rst
@@ -0,0 +1,19 @@
+gRPC Reflection
+====================
+
+What is gRPC reflection?
+---------------------------------------------
+
+Check this out `gRPC Python Server Reflection <https://github.com/grpc/grpc/blob/master/doc/python/server_reflection.md>`_
+
+
+Example
+-------
+
+Refer to the GitHub `reflection example <https://github.com/grpc/grpc/blob/master/examples/python/helloworld/greeter_server_with_reflection.py>`_
+
+
+Module Contents
+---------------
+
+.. automodule:: grpc_reflection.v1alpha.reflection
diff --git a/doc/python/sphinx/grpc_testing.rst b/doc/python/sphinx/grpc_testing.rst
new file mode 100644
index 0000000000..adfeb8b384
--- /dev/null
+++ b/doc/python/sphinx/grpc_testing.rst
@@ -0,0 +1,7 @@
+gRPC Testing
+====================
+
+Module Contents
+---------------
+
+.. automodule:: grpc_testing
diff --git a/doc/python/sphinx/index.rst b/doc/python/sphinx/index.rst
new file mode 100644
index 0000000000..b602b2934f
--- /dev/null
+++ b/doc/python/sphinx/index.rst
@@ -0,0 +1,24 @@
+Welcome to gRPC Python's documentation!
+=======================================
+
+Version: |version| Release: |release|
+
+API Reference
+=============
+
+.. toctree::
+   :caption: Contents:
+
+   api
+   grpc_health_checking
+   grpc_reflection
+   grpc_testing
+   glossary
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/setup.py b/setup.py
index 7ac766c8c2..ae86e6c9fb 100644
--- a/setup.py
+++ b/setup.py
@@ -289,8 +289,7 @@ if not PY3:
   INSTALL_REQUIRES += ('futures>=2.2.0', 'enum34>=1.0.4')
 
 SETUP_REQUIRES = INSTALL_REQUIRES + (
-    'sphinx>=1.3',
-    'sphinx_rtd_theme>=0.1.8',
+    'Sphinx~=1.8.1',
     'six>=1.10',
   ) if ENABLE_DOCUMENTATION_BUILD else ()
 
diff --git a/src/python/grpcio/commands.py b/src/python/grpcio/commands.py
index dc6779740f..b805f4277b 100644
--- a/src/python/grpcio/commands.py
+++ b/src/python/grpcio/commands.py
@@ -39,36 +39,6 @@ PROTO_STEM = os.path.join(GRPC_STEM, 'src', 'proto')
 PROTO_GEN_STEM = os.path.join(GRPC_STEM, 'src', 'python', 'gens')
 CYTHON_STEM = os.path.join(PYTHON_STEM, 'grpc', '_cython')
 
-CONF_PY_ADDENDUM = """
-extensions.append('sphinx.ext.napoleon')
-napoleon_google_docstring = True
-napoleon_numpy_docstring = True
-napoleon_include_special_with_doc = True
-
-html_theme = 'sphinx_rtd_theme'
-copyright = "2016, The gRPC Authors"
-"""
-
-API_GLOSSARY = """
-
-Glossary
-================
-
-.. glossary::
-
-  metadatum
-    A key-value pair included in the HTTP header.  It is a 
-    2-tuple where the first entry is the key and the
-    second is the value, i.e. (key, value).  The metadata key is an ASCII str,
-    and must be a valid HTTP header name.  The metadata value can be
-    either a valid HTTP ASCII str, or bytes.  If bytes are provided,
-    the key must end with '-bin', i.e.
-    ``('binary-metadata-bin', b'\\x00\\xFF')``
-
-  metadata
-    A sequence of metadatum.
-"""
-
 
 class CommandError(Exception):
     """Simple exception class for GRPC custom commands."""
@@ -124,25 +94,14 @@ class SphinxDocumentation(setuptools.Command):
     def run(self):
         # We import here to ensure that setup.py has had a chance to install the
         # relevant package eggs first.
-        import sphinx
-        import sphinx.apidoc
-        metadata = self.distribution.metadata
-        src_dir = os.path.join(PYTHON_STEM, 'grpc')
-        sys.path.append(src_dir)
-        sphinx.apidoc.main([
-            '', '--force', '--full', '-H', metadata.name, '-A', metadata.author,
-            '-V', metadata.version, '-R', metadata.version, '-o',
-            os.path.join('doc', 'src'), src_dir
-        ])
-        conf_filepath = os.path.join('doc', 'src', 'conf.py')
-        with open(conf_filepath, 'a') as conf_file:
-            conf_file.write(CONF_PY_ADDENDUM)
-        glossary_filepath = os.path.join('doc', 'src', 'grpc.rst')
-        with open(glossary_filepath, 'a') as glossary_filepath:
-            glossary_filepath.write(API_GLOSSARY)
-        sphinx.main(
-            ['', os.path.join('doc', 'src'),
-             os.path.join('doc', 'build')])
+        import sphinx.cmd.build
+        source_dir = os.path.join(GRPC_STEM, 'doc', 'python', 'sphinx')
+        target_dir = os.path.join(GRPC_STEM, 'doc', 'build')
+        exit_code = sphinx.cmd.build.build_main(
+            ['-b', 'html', '-W', '--keep-going', source_dir, target_dir])
+        if exit_code is not 0:
+            raise CommandError(
+                "Documentation generation has warnings or errors")
 
 
 class BuildProjectMetadata(setuptools.Command):
diff --git a/src/python/grpcio/grpc/__init__.py b/src/python/grpcio/grpc/__init__.py
index 863696d236..43e382b875 100644
--- a/src/python/grpcio/grpc/__init__.py
+++ b/src/python/grpcio/grpc/__init__.py
@@ -48,11 +48,13 @@ class Future(six.with_metaclass(abc.ABCMeta)):
         Returns:
             bool:
             Returns True if the computation was canceled.
+
             Returns False under all other circumstances, for example:
+
             1. computation has begun and could not be canceled.
             2. computation has finished
             3. computation is scheduled for execution and it is impossible
-              to determine its state without blocking.
+                to determine its state without blocking.
         """
         raise NotImplementedError()
 
@@ -66,7 +68,9 @@ class Future(six.with_metaclass(abc.ABCMeta)):
             bool:
             Returns True if the computation was cancelled before its result became
             available.
-            False under all other circumstances, for example:
+
+            Returns False under all other circumstances, for example:
+
             1. computation was not cancelled.
             2. computation's result is available.
         """
@@ -79,9 +83,9 @@ class Future(six.with_metaclass(abc.ABCMeta)):
         This method does not block.
 
         Returns:
-            bool:
             Returns True if the computation is scheduled for execution or
             currently executing.
+
             Returns False if the computation already executed or was cancelled.
         """
         raise NotImplementedError()
@@ -210,7 +214,33 @@ class ChannelConnectivity(enum.Enum):
 
 @enum.unique
 class StatusCode(enum.Enum):
-    """Mirrors grpc_status_code in the gRPC Core."""
+    """Mirrors grpc_status_code in the gRPC Core.
+
+    Attributes:
+      OK: Not an error; returned on success
+      CANCELLED: The operation was cancelled (typically by the caller).
+      UNKNOWN: Unknown error.
+      INVALID_ARGUMENT: Client specified an invalid argument.
+      DEADLINE_EXCEEDED: Deadline expired before operation could complete.
+      NOT_FOUND: Some requested entity (e.g., file or directory) was not found.
+      ALREADY_EXISTS: Some entity that we attempted to create (e.g., file or directory)
+        already exists.
+      PERMISSION_DENIED: The caller does not have permission to execute the specified
+        operation.
+      UNAUTHENTICATED: The request does not have valid authentication credentials for the
+        operation.
+      RESOURCE_EXHAUSTED: Some resource has been exhausted, perhaps a per-user quota, or
+        perhaps the entire file system is out of space.
+      FAILED_PRECONDITION: Operation was rejected because the system is not in a state
+        required for the operation's execution.
+      ABORTED: The operation was aborted, typically due to a concurrency issue
+        like sequencer check failures, transaction aborts, etc.
+      UNIMPLEMENTED: Operation is not implemented or not supported/enabled in this service.
+      INTERNAL: Internal errors.  Means some invariants expected by underlying
+        system has been broken.
+      UNAVAILABLE: The service is currently unavailable.
+      DATA_LOSS: Unrecoverable data loss or corruption.
+    """
     OK = (_cygrpc.StatusCode.ok, 'ok')
     CANCELLED = (_cygrpc.StatusCode.cancelled, 'cancelled')
     UNKNOWN = (_cygrpc.StatusCode.unknown, 'unknown')
@@ -450,8 +480,7 @@ class StreamUnaryClientInterceptor(six.with_metaclass(abc.ABCMeta)):
             actual RPC on the underlying Channel. It is the interceptor's
             responsibility to call it if it decides to move the RPC forward.
             The interceptor can use
-            `response_future = continuation(client_call_details,
-                                            request_iterator)`
+            `response_future = continuation(client_call_details, request_iterator)`
             to continue with the RPC. `continuation` returns an object that is
             both a Call for the RPC and a Future. In the event of RPC completion,
             the return Call-Future's result value will be the response message
@@ -462,11 +491,11 @@ class StreamUnaryClientInterceptor(six.with_metaclass(abc.ABCMeta)):
           request_iterator: An iterator that yields request values for the RPC.
 
         Returns:
-            An object that is both a Call for the RPC and a Future.
-            In the event of RPC completion, the return Call-Future's
-            result value will be the response message of the RPC.
-            Should the event terminate with non-OK status, the returned
-            Call-Future's exception value will be an RpcError.
+          An object that is both a Call for the RPC and a Future.
+          In the event of RPC completion, the return Call-Future's
+          result value will be the response message of the RPC.
+          Should the event terminate with non-OK status, the returned
+          Call-Future's exception value will be an RpcError.
         """
         raise NotImplementedError()
 
@@ -482,13 +511,13 @@ class StreamStreamClientInterceptor(six.with_metaclass(abc.ABCMeta)):
                                 request_iterator):
         """Intercepts a stream-stream invocation.
 
+        Args:
           continuation: A function that proceeds with the invocation by
             executing the next interceptor in chain or invoking the
             actual RPC on the underlying Channel. It is the interceptor's
             responsibility to call it if it decides to move the RPC forward.
             The interceptor can use
-            `response_iterator = continuation(client_call_details,
-                                              request_iterator)`
+            `response_iterator = continuation(client_call_details, request_iterator)`
             to continue with the RPC. `continuation` returns an object that is
             both a Call for the RPC and an iterator for response values.
             Drawing response values from the returned Call-iterator may
@@ -499,10 +528,10 @@ class StreamStreamClientInterceptor(six.with_metaclass(abc.ABCMeta)):
           request_iterator: An iterator that yields request values for the RPC.
 
         Returns:
-            An object that is both a Call for the RPC and an iterator of
-            response values. Drawing response values from the returned
-            Call-iterator may raise RpcError indicating termination of
-            the RPC with non-OK status.
+          An object that is both a Call for the RPC and an iterator of
+          response values. Drawing response values from the returned
+          Call-iterator may raise RpcError indicating termination of
+          the RPC with non-OK status.
         """
         raise NotImplementedError()
 
@@ -972,8 +1001,7 @@ class ServicerContext(six.with_metaclass(abc.ABCMeta, RpcContext)):
         """Gets one or more peer identity(s).
 
         Equivalent to
-        servicer_context.auth_context().get(
-            servicer_context.peer_identity_key())
+        servicer_context.auth_context().get(servicer_context.peer_identity_key())
 
         Returns:
           An iterable of the identities, or None if the call is not