New Python documentation generation

* Use templates instead of generating them every time
* Theme changed
* Add grpc_* modules
* APIs grouped
* No documentation for class members without docstring
* Add docstring for status code

7 files changed, 328 insertions, 0 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`