From b898529cfaceba6bc5887f6b2bddbc0a5bc1d7c8 Mon Sep 17 00:00:00 2001 From: Kim van der Riet Date: Mon, 9 Dec 2019 13:56:27 -0500 Subject: [PATCH 1/2] Removed sections from docs that require automodapi module, replaced with static tables instead. CMakeLists updated to not search for automodapi. --- python/CMakeLists.txt | 3 +- python/docs/conf.py | 1 - python/docs/proton.handlers.rst | 23 +++--- python/docs/proton.reactor.rst | 55 ++++++++----- python/docs/proton.rst | 166 ++++++++++++++++++++++++++-------------- python/docs/proton.utils.rst | 27 ++++--- 6 files changed, 179 insertions(+), 96 deletions(-) diff --git a/python/CMakeLists.txt b/python/CMakeLists.txt index cb36b1c..a396319 100644 --- a/python/CMakeLists.txt +++ b/python/CMakeLists.txt @@ -120,8 +120,7 @@ py_compile(${CMAKE_CURRENT_SOURCE_DIR} "${pysrc}" PROTON_ARTIFACTS) # Sphinx documentation check_python_module("sphinx" SPHINX_MODULE_FOUND) -check_python_module("sphinx_automodapi" SPHINX_AUTOMODAPI_MODULE_FOUND) -if (NOT SPHINX_MODULE_FOUND OR NOT SPHINX_AUTOMODAPI_MODULE_FOUND) +if (NOT SPHINX_MODULE_FOUND) message(STATUS "Sphinx modules not found; doc generation disabled.") else () add_custom_target(docs-py diff --git a/python/docs/conf.py b/python/docs/conf.py index 3f95201..e57ebfe 100644 --- a/python/docs/conf.py +++ b/python/docs/conf.py @@ -51,7 +51,6 @@ except IOError: # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx_automodapi.automodapi', # needed for the module summaries (.. autosummary::) 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.mathjax', # needed for math formulas on some versions of Sphinx diff --git a/python/docs/proton.handlers.rst b/python/docs/proton.handlers.rst index 662eb23..296d6f3 100644 --- a/python/docs/proton.handlers.rst +++ b/python/docs/proton.handlers.rst @@ -9,11 +9,15 @@ Module Summary | -.. autosummary:: - - MessagingHandler - TransactionHandler - TransactionalClientHandler ++-------------------------------------+----------------------------------------------------------------------------------------+ +| :class:`MessagingHandler` | A general purpose handler that makes the proton-c events somewhat simpler to deal with | +| | and/or avoids repetitive tasks for common use cases. | ++-------------------------------------+----------------------------------------------------------------------------------------+ +| :class:`TransactionHandler` | The interface for transaction handlers - ie objects that want to be notified of state | +| | changes related to a transaction. | ++-------------------------------------+----------------------------------------------------------------------------------------+ +| :class:`TransactionalClientHandler` | An extension to the MessagingHandler for applications using transactions. | ++-------------------------------------+----------------------------------------------------------------------------------------+ | @@ -22,10 +26,11 @@ Exceptions | -.. autosummary:: - - Reject - Release ++------------------+-----------------------------------------------------------+ +| :class:`Reject` | An exception that indicates a message should be rejected. | ++------------------+-----------------------------------------------------------+ +| :class:`Release` | An exception that indicates a message should be released. | ++------------------+-----------------------------------------------------------+ | diff --git a/python/docs/proton.reactor.rst b/python/docs/proton.reactor.rst index 750f042..23740ef 100644 --- a/python/docs/proton.reactor.rst +++ b/python/docs/proton.reactor.rst @@ -9,12 +9,20 @@ Module Summary | -.. autosummary:: - Container - ApplicationEvent - EventInjector - Backoff - Transaction ++---------------------------+----------------------------------------------------------------------------------------------------+ +| :class:`Container` | A representation of the AMQP concept of a ‘container’, which loosely speaking is something that | +| | establishes links to or from another container, over which messages are transfered. | ++---------------------------+----------------------------------------------------------------------------------------------------+ +| :class:`ApplicationEvent` | Application defined event, which can optionally be associated with an engine object and or an | +| | arbitrary subject. | ++---------------------------+----------------------------------------------------------------------------------------------------+ +| :class:`EventInjector` | Can be added to a :class:`Container` to allow events to be triggered by an external thread but | +| | handled on the event thread associated with the container. | ++---------------------------+----------------------------------------------------------------------------------------------------+ +| :class:`Backoff` | A reconnect strategy involving an increasing delay between retries, up to a maximum or 10 seconds. | ++---------------------------+----------------------------------------------------------------------------------------------------+ +| :class:`Transaction` | Tracks the state of an AMQP 1.0 local transaction. | ++---------------------------+----------------------------------------------------------------------------------------------------+ | @@ -25,18 +33,29 @@ Link Options The methods :meth:`Container.create_receiver` and :meth:`Container.create_sender` take one or more link options to allow the details of the links to be customized. -.. autosummary:: - LinkOption - ReceiverOption - SenderOption - AtLeastOnce - AtMostOnce - DynamicNodeProperties - Filter - Selector - DurableSubscription - Copy - Move ++--------------------------------+----------------------------------------------------------------------------------+ +| :class:`LinkOption` | Abstract interface for link configuration options. | ++--------------------------------+----------------------------------------------------------------------------------+ +| :class:`ReceiverOption` | Abstract class for receiver options. | ++--------------------------------+----------------------------------------------------------------------------------+ +| :class:`SenderOption` | Abstract class for sender options. | ++--------------------------------+----------------------------------------------------------------------------------+ +| :class:`AtLeastOnce` | Set at-least-once delivery semantics for message delivery. | ++--------------------------------+----------------------------------------------------------------------------------+ +| :class:`AtMostOnce` | Set at-most-once delivery semantics for message delivery. | ++--------------------------------+----------------------------------------------------------------------------------+ +| :class:`DynamicNodeProperties` | Allows a map of link properties to be set on a link. | ++--------------------------------+----------------------------------------------------------------------------------+ +| :class:`Filter` | Receiver option which allows incoming messages to be filtered. | ++--------------------------------+----------------------------------------------------------------------------------+ +| :class:`Selector` | Configures a receiver with a message selector filter. | ++--------------------------------+----------------------------------------------------------------------------------+ +| :class:`DurableSubscription` | Receiver option which sets both the configuration and delivery state to durable. | ++--------------------------------+----------------------------------------------------------------------------------+ +| :class:`Copy` | Receiver option which copies messages to the receiver. | ++--------------------------------+----------------------------------------------------------------------------------+ +| :class:`Move` | Receiver option which moves messages to the receiver (rather than copying). | ++--------------------------------+----------------------------------------------------------------------------------+ | diff --git a/python/docs/proton.rst b/python/docs/proton.rst index 2a92346..4dd1e2d 100644 --- a/python/docs/proton.rst +++ b/python/docs/proton.rst @@ -9,31 +9,57 @@ Module Summary | -.. autosummary:: - - AnnotationDict - Condition - Connection - Data - Delivery - Disposition - Endpoint - Event - EventType - Link - Message - PropertyDict - Receiver - SASL - Sender - Session - SSL - SSLDomain - SSLSessionDetails - SymbolList - Terminus - Transport - Url ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`AnnotationDict` | A dictionary that only takes :class:`symbol` or :class:`ulong` types as a key. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Condition` | An AMQP Condition object. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Connection` | A representation of an AMQP connection. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Data` | Provides an interface for decoding, extracting, creating, and encoding arbitrary AMQP data. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Delivery` | Tracks and/or records the delivery of a message over a link. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Disposition` | A delivery state. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Endpoint` | Abstract class from which :class:`Connection`, :class:`Session` and :class:`Link` are derived, | +| | and which defines the state of these classes. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Event` | Notification of a state change in the protocol engine. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`EventType` | Connects an event number to an event name, and is used internally by :class:`Event` to represent| +| | all known event types. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Link` | A representation of an AMQP link (a unidirectional channel for transferring messages), of which | +| | there are two concrete implementations, :class:`Sender` and :class:`Receiver`. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Message` | A mutable holder of message content. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`PropertyDict` | A dictionary that only takes :class:`symbol` types as a key. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Receiver` | A link over which messages are received. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`SASL` | The SASL layer is responsible for establishing an authenticated and/or encrypted tunnel over | +| | which AMQP frames are passed between peers. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Sender` | A link over which messages are sent. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Session` | A container of links. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`SSL` | An SSL session associated with a transport. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`SSLDomain` | An SSL configuration domain, used to hold the SSL configuration for one or more SSL sessions. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`SSLSessionDetails` | Unique identifier for the SSL session. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`SymbolList` | A list that can only hold :class:`symbol` elements. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Terminus` | A source or target for messages. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Transport` | A network channel supporting an AMQP connection. | ++----------------------------+-------------------------------------------------------------------------------------------------+ +| :class:`Url` | **DEPRECATED** Simple URL parser/constructor. | ++----------------------------+-------------------------------------------------------------------------------------------------+ | @@ -42,19 +68,29 @@ Exceptions | -.. autosummary:: - - ConnectionException - DataException - LinkException - MessageException - ProtonException - SessionException - SSLUnavailable - SSLException - Timeout - Interrupt - TransportException ++------------------------------+-----------------------------------------------------------------------------------------+ +| :class:`ConnectionException` | An exception class raised when exceptions or errors related to a connection arise. | ++------------------------------+-----------------------------------------------------------------------------------------+ +| :class:`DataException` | The DataException class is the root of the Data exception hierarchy. | ++------------------------------+-----------------------------------------------------------------------------------------+ +| :class:`LinkException` | An exception class raised when exceptions or errors related to a link arise. | ++------------------------------+-----------------------------------------------------------------------------------------+ +| :class:`MessageException` | The MessageException class is the root of the message exception hierarchy. | ++------------------------------+-----------------------------------------------------------------------------------------+ +| :class:`ProtonException` | The root of the proton exception hierarchy. | ++------------------------------+-----------------------------------------------------------------------------------------+ +| :class:`SessionException` | An exception class raised when exceptions or errors related to a session arise. | ++------------------------------+-----------------------------------------------------------------------------------------+ +| :class:`SSLUnavailable` | An exception class raised when exceptions or errors related to SSL availability arise. | ++------------------------------+-----------------------------------------------------------------------------------------+ +| :class:`SSLException` | An exception class raised when exceptions or errors related to SSL usage arise. | ++------------------------------+-----------------------------------------------------------------------------------------+ +| :class:`Timeout` | A timeout exception indicates that a blocking operation has timed out. | ++------------------------------+-----------------------------------------------------------------------------------------+ +| :class:`Interrupt` | An interrupt exception indicates that a blocking operation was interrupted. | ++------------------------------+-----------------------------------------------------------------------------------------+ +| :class:`TransportException` | An exception class raised when exceptions or errors related to the AMQP transport arise.| ++------------------------------+-----------------------------------------------------------------------------------------+ | @@ -63,25 +99,41 @@ AMQP Types | -.. autosummary:: - :nosignatures: - - Array - byte - char - Described - decimal32 - decimal64 - decimal128 - float32 - int32 - short - symbol - timestamp - ubyte - uint - ulong - ushort +Some AMQP types are represented by native Python types. See :ref:`types` for a full list of AMQP types. + ++---------------------+------------------------------------------------------------+ +| :class:`Array` | An AMQP array, a sequence of AMQP values of a single type. | ++---------------------+------------------------------------------------------------+ +| :class:`byte` | The byte AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`char` | The char AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`Described` | A described AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`decimal32` | The decimal32 AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`decimal64` | The decimal64 AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`decimal128` | The decimal128 AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`float32` | The float AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`int32` | The signed int AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`short` | The short AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`symbol` | The symbol AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`timestamp` | The timestamp AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`ubyte` | The unsigned byte AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`uint` | The unsigned int AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`ulong` | The ulong AMQP type. | ++---------------------+------------------------------------------------------------+ +| :class:`ushort` | The unsigned short AMQP type. | ++---------------------+------------------------------------------------------------+ | diff --git a/python/docs/proton.utils.rst b/python/docs/proton.utils.rst index 8f2404d..219968a 100644 --- a/python/docs/proton.utils.rst +++ b/python/docs/proton.utils.rst @@ -9,11 +9,15 @@ Module Summary | -.. autosummary:: - BlockingConnection - BlockingSender - BlockingReceiver - SyncRequestResponse ++------------------------------+-----------------------------------------------------------------------+ +| :class:`BlockingConnection` | A synchronous style connection wrapper. | ++------------------------------+-----------------------------------------------------------------------+ +| :class:`BlockingSender` | A synchronous sender wrapper. | ++------------------------------+-----------------------------------------------------------------------+ +| :class:`BlockingReceiver` | A synchronous receiver wrapper. | ++------------------------------+-----------------------------------------------------------------------+ +| :class:`SyncRequestResponse` | Implementation of the synchronous request-response (aka RPC) pattern. | ++------------------------------+-----------------------------------------------------------------------+ | @@ -22,10 +26,15 @@ Exceptions | -.. autosummary:: - SendException - LinkDetached - ConnectionClosed ++---------------------------+---------------------------------------------------------------------------------------------------+ +| :class:`SendException` | Exception used to indicate an exceptional state/condition on a send request. | ++---------------------------+---------------------------------------------------------------------------------------------------+ +| :class:`LinkDetached` | The exception raised when the remote peer unexpectedly closes a link in a blocking context, or | +| | an unexpected link error occurs. | ++---------------------------+---------------------------------------------------------------------------------------------------+ +| :class:`ConnectionClosed` | The exception raised when the remote peer unexpectedly closes a connection in a blocking context, | +| | or an unexpected connection error occurs. | ++---------------------------+---------------------------------------------------------------------------------------------------+ | -- 1.8.3.1 From afa47527ea5fc01a7e8497779277c269930a5aa5 Mon Sep 17 00:00:00 2001 From: Kim van der Riet Date: Tue, 10 Dec 2019 10:56:30 -0500 Subject: [PATCH 2/2] Changed Sphinx invocation from sphinx to sphinx-build for RHEL7 --- python/CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python/CMakeLists.txt b/python/CMakeLists.txt index a396319..23c7eb4 100644 --- a/python/CMakeLists.txt +++ b/python/CMakeLists.txt @@ -127,7 +127,7 @@ else () COMMAND ${PN_ENV_SCRIPT} -- PYTHONPATH=${CMAKE_CURRENT_BINARY_DIR}:${CMAKE_CURRENT_SOURCE_DIR} LD_LIBRARY_PATH="${CMAKE_CURRENT_BINARY_DIR}/c" - ${PYTHON_EXECUTABLE} -m sphinx "${CMAKE_CURRENT_SOURCE_DIR}/docs" "${CMAKE_CURRENT_BINARY_DIR}/docs") + sphinx-build "${CMAKE_CURRENT_SOURCE_DIR}/docs" "${CMAKE_CURRENT_BINARY_DIR}/docs") add_dependencies(docs docs-py) install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/docs/" DESTINATION "${PROTON_SHARE}/docs/api-py" -- 1.8.3.1