[tor-commits] [stem/master] Revised API docs for stem.descriptor

[atagar at torproject.org]

commit 6925f6147120b645338f20abb8597d7b7787cf31
Author: Damian Johnson <atagar at torproject.org>
Date:   Thu Oct 25 18:31:02 2012 -0700

    Revised API docs for stem.descriptor
---
 docs/api.rst                   |    2 ++
 docs/contents.rst              |    2 ++
 docs/descriptor/descriptor.rst |    5 +++++
 stem/descriptor/__init__.py    |   16 ++++++++--------
 4 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 25e870b..0e6d35a 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -13,3 +13,5 @@ Descriptors
 * `stem.descriptor.reader <descriptor/reader.html>`_ - Reads and parses descriptor files from disk.
 * `stem.descriptor.export <descriptor/export.html>`_ - Exports descriptors to other formats.
 
+* `stem.descriptor <descriptor/descriptor.html>`_ - Base class for descriptors.
+
diff --git a/docs/contents.rst b/docs/contents.rst
index c40ada6..3026ccc 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -11,6 +11,8 @@ Contents
    descriptor/export
    descriptor/reader
 
+   descriptor/descriptor
+
    types/exit_policy
    types/version
 
diff --git a/docs/descriptor/descriptor.rst b/docs/descriptor/descriptor.rst
new file mode 100644
index 0000000..0273b53
--- /dev/null
+++ b/docs/descriptor/descriptor.rst
@@ -0,0 +1,5 @@
+Descriptor
+==========
+
+.. automodule:: stem.descriptor.__init__
+
diff --git a/stem/descriptor/__init__.py b/stem/descriptor/__init__.py
index 9d33ab7..a6aac75 100644
--- a/stem/descriptor/__init__.py
+++ b/stem/descriptor/__init__.py
@@ -60,8 +60,8 @@ def parse_file(path, descriptor_file):
   :returns: iterator for :class:`stem.descriptor.Descriptor` instances in the file
   
   :raises:
-    * TypeError if we can't match the contents of the file to a descriptor type
-    * IOError if unable to read from the descriptor_file
+    * **TypeError** if we can't match the contents of the file to a descriptor type
+    * **IOError** if unable to read from the descriptor_file
   """
   
   import stem.descriptor.server_descriptor
@@ -149,7 +149,7 @@ class Descriptor(object):
     """
     Provides the absolute path that we loaded this descriptor from.
     
-    :returns: str with the absolute path of the descriptor source
+    :returns: **str** with the absolute path of the descriptor source
     """
     
     return self._path
@@ -160,7 +160,7 @@ class Descriptor(object):
     not know how to process. This is most common due to new descriptor fields
     that this library does not yet know how to process. Patches welcome!
     
-    :returns: list of lines of unrecognized content
+    :returns: **list** of lines of unrecognized content
     """
     
     raise NotImplementedError
@@ -183,7 +183,7 @@ def _read_until_keywords(keywords, descriptor_file, inclusive = False, ignore_fi
   :param bool skip: skips buffering content, returning None
   :param int end_position: end if we reach this point in the file
   
-  :returns: list with the lines until we find one of the keywords
+  :returns: **list** with the lines until we find one of the keywords
   """
   
   content = None if skip else []
@@ -231,9 +231,9 @@ def _get_pseudo_pgp_block(remaining_contents):
   
   :param list remaining_contents: lines to be checked for a public key block
   
-  :returns: str with the armor wrapped contents or None if it doesn't exist
+  :returns: **str** with the armor wrapped contents or None if it doesn't exist
   
-  :raises: ValueError if the contents starts with a key block but it's malformed (for instance, if it lacks an ending line)
+  :raises: **ValueError** if the contents starts with a key block but it's malformed (for instance, if it lacks an ending line)
   """
   
   if not remaining_contents:
@@ -277,7 +277,7 @@ def _get_descriptor_components(raw_contents, validate, extra_keywords = ()):
   :param list extra_keywords: entity keywords to put into a separate listing with ordering intact
   
   :returns:
-    collections.OrderedDict with the 'keyword => (value, pgp key) entries'
+    **collections.OrderedDict** with the 'keyword => (value, pgp key) entries'
     mappings. If a extra_keywords was provided then this instead provides a two
     value tuple, the second being a list of those entries.
   """