PROTON-2164: Update to remove dependency on automodapi extension to Sphinx
diff --git a/INSTALL.md b/INSTALL.md
index 32405f2..8e42697 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -51,7 +51,6 @@
# Dependencies needed to generate documentation
$ yum install python-sphinx # Python
- $ pip install --user sphinx-automodapi
$ yum install rubygem-yard # Ruby
$ yum install doxygen # C, C++
@@ -74,7 +73,6 @@
# dependencies needed for python docs
$ apt-get install python-sphinx
- $ pip install --user sphinx-automodapi
From the directory where you found this `INSTALL.md` file:
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 @@
# 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 @@
# 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 @@
|
-.. 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 @@
|
-.. 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 @@
|
-.. 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 @@
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..724c388 100644
--- a/python/docs/proton.rst
+++ b/python/docs/proton.rst
@@ -9,31 +9,57 @@
|
-.. 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,46 +68,72 @@
|
-.. 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.|
++------------------------------+-----------------------------------------------------------------------------------------+
|
AMQP Types
==========
+**NOTE:** Some AMQP types are represented by native Python types. This table contains only classes for non-native
+Python types defined in this module. See :ref:`types` for a full list of AMQP types.
|
-.. autosummary::
- :nosignatures:
-
- Array
- byte
- char
- Described
- decimal32
- decimal64
- decimal128
- float32
- int32
- short
- symbol
- timestamp
- ubyte
- uint
- ulong
- ushort
++---------------------+------------------------------------------------------------+
+| :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 @@
|
-.. 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 @@
|
-.. 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. |
++---------------------------+---------------------------------------------------------------------------------------------------+
|
