Update docs some more.

* Add API docs for protocol parsing, including the receiver interface.
* Change a bunch of fixed-width text to links.
* Update the docstrings in the parsley module.

Author: habnabit

doc/reference.rst

@@ -74,6 +74,74 @@ Python API
    :members:
 
 
+Protocol parsing API
+====================
+
+.. py:module:: ometa.protocol
+
+.. py:class:: ParserProtocol
+
+   The Twisted ``Protocol`` subclass used for :ref:`parsing stream protocols
+   using Parsley <protocol-parsing>`. It has two public attributes:
+
+   .. py:attribute:: sender
+
+      After the connection is established, this attribute will refer to the
+      sender created by the sender factory of the :class:`ParserProtocol`.
+
+   .. py:attribute:: receiver
+
+      After the connection is established, this attribute will refer to the
+      receiver created by the receiver factory of the :class:`ParserProtocol`.
+
+   It's common to also add a ``factory`` attribute to the
+   :class:`ParserProtocol` from its factory's ``buildProtocol`` method, but
+   this isn't strictly required or guaranteed to be present.
+
+   Subclassing or instantiating :class:`ParserProtocol` is not necessary;
+   :func:`~parsley.makeProtocol` is sufficient and requires less boilerplate.
+
+.. _receivers:
+
+.. py:class:: Receiver
+
+   :class:`Receiver` is not a real class but is used here for demonstration
+   purposes to indicate the required API.
+
+   .. py:attribute:: currentRule
+
+      :class:`ParserProtocol` examines the :attr:`currentRule` attribute at the
+      beginning of parsing as well as after every time a rule has completely
+      matched. At these times, the rule with the same name as the value of
+      :attr:`currentRule` will be selected to start parsing the incoming stream
+      of data.
+
+   .. py:method:: prepareParsing(parserProtocol)
+
+      :meth:`prepareParsing` is called after the :class:`.ParserProtocol` has
+      established a connection, and is passed the :class:`.ParserProtocol`
+      instance itself.
+
+      :param parserProtocol: An instance of :class:`.ProtocolParser`.
+
+   .. py:method:: finishParsing(reason)
+
+      :meth:`finishParsing` is called if an exception was raised during
+      parsing, or when the :class:`.ParserProtocol` has lost its connection,
+      whichever comes first. It will only be called once.
+
+      An exception raised during parsing can be due to incoming data that
+      doesn't match the current rule or an exception raised calling python code
+      during matching.
+
+      :param reason: A `Failure`_ encapsulating the reason parsing has ended.
+
+.. _senders:
+
+Senders do not have any required API as :class:`ParserProtocol` will never call
+methods on a sender.
+
+
 Built-in Parsley Rules
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -97,3 +165,6 @@ Built-in Parsley Rules
 
 ``exactly(char)``:
    Matches the character `char`.
+
+
+.. _Failure: http://twistedmatrix.com/documents/current/api/twisted.python.failure.Failure.html

doc/tutorial3.rst

@@ -1,3 +1,5 @@
+.. _protocol-parsing:
+
 ===============================================
 Parsley Tutorial Part III: Parsing Network Data
 ===============================================
@@ -16,9 +18,8 @@ framing. Fortunately, Parsley can remove all of this tedium.
 
 With :func:`parsley.makeProtocol`, Parsley can generate a `Twisted`_
 `IProtocol`_-implementing class which will match incoming network data using
-Parsley grammar rules. Before getting started with
-:func:`~parsley.makeProtocol`, let's build a grammar for `netstrings`_. The
-netstrings protocol is very simple::
+Parsley grammar rules. Before getting started with :func:`.makeProtocol`, let's
+build a grammar for `netstrings`_. The netstrings protocol is very simple::
 
   4:spam,4:eggs,
 
@@ -30,9 +31,9 @@ prefixed with one or more ASCII digits followed by a ``:``, and suffixed with a
    :start-after: grammar =
    :end-before: receiveNetstring
 
-:func:`~parsley.makeProtocol` takes, in addition to a grammar, a factory for a
-"sender" and a factory for a "receiver". In the system of objects managed by
-the ``ParserProtocol``, the sender is in charge of writing data to the wire,
+:func:`.makeProtocol` takes, in addition to a grammar, a factory for a "sender"
+and a factory for a "receiver". In the system of objects managed by the
+:class:`.ParserProtocol`, the sender is in charge of writing data to the wire,
 and the receiver has methods called on it by the Parsley rules. To demonstrate
 it, here is the final piece needed in the Parsley grammar for netstrings:
 
@@ -43,44 +44,45 @@ it, here is the final piece needed in the Parsley grammar for netstrings:
 The receiver is always available in Parsley rules with the name ``receiver``,
 allowing Parsley rules to call methods on it.
 
-When data is received over the wire, the ``ParserProtocol`` tries to match the
-received data against the current rule. If the current rule requires more data
-to finish matching, the ``ParserProtocol`` stops and waits until more data
-comes in, then tries to continue matching. This repeats until the current rule
-is completely matched, and then the ``ParserProtocol`` starts matching any
-leftover data against the current rule again.
+When data is received over the wire, the :class:`.ParserProtocol` tries to
+match the received data against the current rule. If the current rule requires
+more data to finish matching, the :class:`.ParserProtocol` stops and waits
+until more data comes in, then tries to continue matching. This repeats until
+the current rule is completely matched, and then the :class:`.ParserProtocol`
+starts matching any leftover data against the current rule again.
 
-One specifies the current rule by setting a ``currentRule`` attribute on the
-receiver, which the ``ParserProtocol`` looks at before doing any parsing.
-Changing the current rule is addressed in the :ref:`Switching rules
+One specifies the current rule by setting a :attr:`.currentRule` attribute on
+the receiver, which the :class:`.ParserProtocol` looks at before doing any
+parsing. Changing the current rule is addressed in the :ref:`Switching rules
 <switching-rules>` section.
 
-Since the ``ParserProtocol`` will never modify the ``currentRule`` attribute
-itself, the default behavior is to keep using the same rule. Parsing netstrings
-doesn't require any rule changing, so, the default behavior of continuing to
-use the same rule is fine.
+Since the :class:`.ParserProtocol` will never modify the :attr:`.currentRule`
+attribute itself, the default behavior is to keep using the same rule. Parsing
+netstrings doesn't require any rule changing, so, the default behavior of
+continuing to use the same rule is fine.
 
 Both the sender factory and receiver factory are constructed when the
-``ParserProtocol``'s connection is established. The sender factory is a
-one-argument callable which will be passed the ``ParserProtocol``'s
+:class:`.ParserProtocol`'s connection is established. The sender factory is a
+one-argument callable which will be passed the :class:`.ParserProtocol`'s
 `Transport`_. This allows the sender to send data over the transport. For
 example:
 
 .. literalinclude:: _static/listings/tutorial3-netstrings.py
    :pyobject: NetstringSender
 
 The receiver factory is another one-argument callable which is passed the
-constructed sender. The returned object must at least have ``prepareParsing``
-and ``finishParsing`` methods. ``prepareParsing`` is called with the
-``ParserProtocol`` instance when a connection is established (i.e. in the
-``connectionMade`` of the ``ParserProtocol``) and ``finishParsing`` is called
-when a connection is closed (i.e. in the ``connectionLost`` of the
-``ParserProtocol``).
+constructed sender. The returned object must at least have
+:meth:`.prepareParsing` and :meth:`.finishParsing` methods.
+:meth:`.prepareParsing` is called with the :class:`.ParserProtocol` instance
+when a connection is established (i.e. in the ``connectionMade`` of the
+:class:`.ParserProtocol`) and :meth:`.finishParsing` is called when a
+connection is closed (i.e. in the ``connectionLost`` of the
+:class:`.ParserProtocol`).
 
 .. note::
-   Both the receiver factory and its returned object's ``prepareParsing`` are
-   called at in the ``ParserProtocol``'s ``connectionMade`` method; this
-   separation is for ease of testing receivers.
+   Both the receiver factory and its returned object's :meth:`.prepareParsing`
+   are called at in the :class:`.ParserProtocol`'s ``connectionMade`` method;
+   this separation is for ease of testing receivers.
 
 To demonstrate a receiver, here is a simple receiver that receives netstrings
 and echos the same netstrings back:
@@ -105,8 +107,8 @@ Intermezzo: error reporting
 If an exception is raised from within Parsley during parsing, whether it's due
 to input not matching the current rule or an exception being raised from code
 the grammar calls, the connection will be immediately closed. The traceback
-will be captured as a `Failure`_ and passed to the ``finishParsing`` method of
-the receiver.
+will be captured as a `Failure`_ and passed to the :meth:`.finishParsing`
+method of the receiver.
 
 At present, there is no way to recover from failure.
 
@@ -116,8 +118,8 @@ Composing senders and receivers
 
 The design of senders and receivers is intentional to make composition easy: no
 subclassing is required. While the composition is easy enough to do on your
-own, Parsley provides a function: :func:`~parsley.stack`. It takes a base
-factory followed by zero or more wrappers.
+own, Parsley provides a function: :func:`.stack`. It takes a base factory
+followed by zero or more wrappers.
 
 Its use is extremely simple: ``stack(x, y, z)`` will return a callable suitable
 either as a sender or receiver factory which will, when called with an
@@ -172,18 +174,18 @@ data length and the data. The amended grammar would look something like this:
    :start-after: grammar =
    :end-before: """
 
-Changing the current rule is as simple as changing the ``currentRule``
+Changing the current rule is as simple as changing the :attr:`.currentRule`
 attribute on the receiver. So, the ``netstringReceived`` method could look like
 this:
 
 .. literalinclude:: _static/listings/tutorial3-netstrings2.py
    :pyobject: NetstringReceiver.netstringReceived
 
-While changing the ``currentRule`` attribute can be done at any time, the
-``ParserProtocol`` only examines the ``currentRule`` at the beginning of
-parsing and after a rule has finished matching. As a result, if the
-``currentRule`` changes, the ``ParserProtocol`` will wait until the current
-rule is completely matched before switching rules.
+While changing the :attr:`.currentRule` attribute can be done at any time, the
+:class:`.ParserProtocol` only examines the :attr:`.currentRule` at the
+beginning of parsing and after a rule has finished matching. As a result, if
+the :attr:`.currentRule` changes, the :class:`.ParserProtocol` will wait until
+the current rule is completely matched before switching rules.
 
 :download:`The complete script is also available for download.
 <_static/listings/tutorial3-netstrings2.py>`

parsley.py

@@ -102,16 +102,19 @@ def invokeRule(*args, **kwargs):
 def makeProtocol(source, senderFactory, receiverFactory, bindings=None,
                  name='Grammar'):
     """
-    Create a Protocol implementation from a Parsley grammar.
+    Create a Twisted ``Protocol`` factory from a Parsley grammar.
 
     :param source: A grammar, as a string.
     :param senderFactory: A one-argument callable that takes a twisted
-        ``Transport`` and returns a sender.
-    :param receiverFactory: A two-argument callable that takes the sender
-        returned by the ``senderFactory`` and the ``ParserProtocol`` instance and
-        returns a receiver.
-    :param bindings: A mapping of variable names to objects.
-    :param name: Name used for the generated class.
+        ``Transport`` and returns a :ref:`sender <senders>`.
+    :param receiverFactory: A one-argument callable that takes the sender
+        returned by the ``senderFactory`` and returns a :ref:`receiver
+        <receivers>`.
+    :param bindings: A mapping of variable names to objects which will be
+        accessible from python code in the grammar.
+    :param name: The name used for the generated grammar class.
+    :returns: A nullary callable which will return an instance of
+        :class:`~.ParserProtocol`.
     """
 
     from ometa.protocol import ParserProtocol
@@ -127,8 +130,8 @@ def stack(*wrappers):
     Stack some senders or receivers for ease of wrapping.
 
     ``stack(x, y, z)`` will return a factory usable as a sender or receiver
-    factory which will, when called with a transport or sender, return
-    ``x(y(z(transport-or-sender)))``.
+    factory which will, when called with a transport or sender as an argument,
+    return ``x(y(z(argument)))``.
     """
     if not wrappers:
         raise TypeError('at least one argument is required')