From cabe8d8f10387b49b52488989554d2946caee5aa Mon Sep 17 00:00:00 2001 From: Lidi Zheng Date: Wed, 31 Oct 2018 17:37:33 -0700 Subject: 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 --- doc/python/sphinx/api.rst | 153 +++++++++++++++++++++++++++++ doc/python/sphinx/conf.py | 102 +++++++++++++++++++ doc/python/sphinx/glossary.rst | 16 +++ doc/python/sphinx/grpc_health_checking.rst | 7 ++ doc/python/sphinx/grpc_reflection.rst | 19 ++++ doc/python/sphinx/grpc_testing.rst | 7 ++ doc/python/sphinx/index.rst | 24 +++++ 7 files changed, 328 insertions(+) create mode 100644 doc/python/sphinx/api.rst create mode 100644 doc/python/sphinx/conf.py create mode 100644 doc/python/sphinx/glossary.rst create mode 100644 doc/python/sphinx/grpc_health_checking.rst create mode 100644 doc/python/sphinx/grpc_reflection.rst create mode 100644 doc/python/sphinx/grpc_testing.rst create mode 100644 doc/python/sphinx/index.rst (limited to 'doc/python') 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 `_ + + +Example +------- + +Refer to the GitHub `reflection example `_ + + +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` -- cgit v1.2.3