[
https://issues.apache.org/jira/browse/PROTON-2086?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16917876#comment-16917876
]
ASF GitHub Bot commented on PROTON-2086:
----------------------------------------
kpvdr commented on pull request #186: PROTON-2086: Changed API documentation
from epydoc to Sphinx
URL: https://github.com/apache/qpid-proton/pull/186#discussion_r318665702
##########
File path: python/docs/index.rst
##########
@@ -1,11 +1,134 @@
-Apache Qpid Proton: python documentation
-========================================
+####################################
+Qpid Proton Python API Documentation
+####################################
-Contents:
+The Proton module provides a Python 2.7 and 3.x API for Qpid Proton. It
enables a developer to write Python applications
+that send and receive AMQP messages.
+*******
+Modules
+*******
.. toctree::
:maxdepth: 2
- tutorial
+ proton
+ proton.handlers
+ proton.reactor
+ proton.utils
+
+*****************************************
+About AMQP and the Qpid Proton Python API
+*****************************************
+
+.. toctree::
+ :maxdepth: 1
+
overview
+ tutorial
+
+Key API Features
+================
+
+ * Event-driven API
+ * SSL/TLS secured communication
+ * SASL authentication
+ * Automatic reconnect and failover
+ * Seamless conversion between AMQP and Python data types
+ * AMQP 1.0
+
+Basic API Concepts
+==================
+
+The Qpid Python client API and library allows applications to send and receive
AMQP messages. See :ref:`overview`
+for a more detailed explanation.
+
+Containers
+----------
+
+Messages are transferred between connected peers (or nodes) using **senders**
and **receivers**. Each sender
+or receiver is established over a **connection**. Each connection is
established between two unique **containers**,
+the entry point for the API. The container class
:class:`proton.reactor.Container` is found in the ``proton.reactor``
+module.
+
Review comment:
Possible paragraph to be inserted after Containers, but before Senders:
> Connections
> -----------
>
> A **connection** object tracks the status of an AMQP connection. For
applications which *don't* require either
> authorization or encryption, these may be automatically created by
convenience methods
> :meth:`proton.reactor.Container.create_sender` and/or
:meth:`proton.reactor.Container.create_receiver`.
> However, for applications which *do* require either of these services, a
connection object should be created
> using the convenience method :meth:`proton.reactor.Container.connect` and
providing the required parameters.
> This object should then be passed to the convenience methods
:meth:`proton.reactor.Container.create_sender`
> and/or :meth:`proton.reactor.Container.create_receiver` as needed. The
connection class may be found at
> :class:`proton.Connection`.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
> Move Python API docs to use Sphinx
> ----------------------------------
>
> Key: PROTON-2086
> URL: https://issues.apache.org/jira/browse/PROTON-2086
> Project: Qpid Proton
> Issue Type: Task
> Components: python-binding
> Reporter: Kim van der Riet
> Assignee: Kim van der Riet
> Priority: Major
>
> Currently the Python API docs are generated using ePyDoc. These should be
> switched to using Sphinx.
--
This message was sent by Atlassian Jira
(v8.3.2#803003)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org
For additional commands, e-mail: dev-h...@qpid.apache.org
