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

[atagar at torproject.org]

commit 4b528c5e75bea5892a63ed5d63d3135d46971503
Author: Damian Johnson <atagar at torproject.org>
Date:   Thu Oct 25 09:37:01 2012 -0700

    Revised API docs for stem.descriptor.export
---
 docs/api.rst               |    1 +
 docs/contents.rst          |    2 ++
 docs/descriptor/export.rst |    5 +++++
 stem/descriptor/export.py  |   25 ++++++++++++++++---------
 stem/descriptor/reader.py  |   18 +++++++++---------
 5 files changed, 33 insertions(+), 18 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 0dfe441..25e870b 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -11,4 +11,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.
 
diff --git a/docs/contents.rst b/docs/contents.rst
index 7565543..c40ada6 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -8,7 +8,9 @@ Contents
    download
    tutorial
 
+   descriptor/export
    descriptor/reader
+
    types/exit_policy
    types/version
 
diff --git a/docs/descriptor/export.rst b/docs/descriptor/export.rst
new file mode 100644
index 0000000..a39e777
--- /dev/null
+++ b/docs/descriptor/export.rst
@@ -0,0 +1,5 @@
+Descriptor Exporter
+===================
+
+.. automodule:: stem.descriptor.export
+
diff --git a/stem/descriptor/export.py b/stem/descriptor/export.py
index 16a148d..f000a6d 100644
--- a/stem/descriptor/export.py
+++ b/stem/descriptor/export.py
@@ -1,5 +1,12 @@
 """
-Utilities for exporting descriptors to other formats.
+Toolkit for exporting descriptors to other formats.
+
+**Module Overview:**
+
+::
+
+  export_csv - Exports descriptors to a CSV
+  export_csv_file - Writes exported CSV output to a file
 """
 
 import csv
@@ -17,13 +24,13 @@ def export_csv(descriptors, included_fields = (), excluded_fields = (), header =
   labelled with a header row. Either 'included_fields' or 'excluded_fields' can
   be used for more granular control over its attributes and the order.
   
-  :param Descriptor,list descriptors: descriptor or list of descriptors to be exported
+  :param Descriptor,list descriptors: either a :class:`~stem.descriptor.Descriptor` or list of descriptors to be exported
   :param list included_fields: attributes to include in the csv
   :param list excluded_fields: attributes to exclude from the csv
-  :param bool header: if True then the first line will be a comma separated list of the attribute names
+  :param bool header: if **True** then the first line will be a comma separated list of the attribute names
   
-  :returns: str of the CSV for the descriptors, one per line
-  :raises: ValueError if descriptors contain more than one descriptor type
+  :returns: **str** of the CSV for the descriptors, one per line
+  :raises: **ValueError** if descriptors contain more than one descriptor type
   """
   
   output_buffer = cStringIO.StringIO()
@@ -36,13 +43,13 @@ def export_csv_file(output_file, descriptors, included_fields = (), excluded_fie
   written directly to a file.
   
   :param file output_file: file to be written to
-  :param Descriptor,list descriptors: descriptor or list of descriptors to be exported
+  :param Descriptor,list descriptors: either a :class:`~stem.descriptor.Descriptor` or list of descriptors to be exported
   :param list included_fields: attributes to include in the csv
   :param list excluded_fields: attributes to exclude from the csv
-  :param bool header: if True then the first line will be a comma separated list of the attribute names
+  :param bool header: if **True** then the first line will be a comma separated list of the attribute names
   
-  :returns: str of the CSV for the descriptors, one per line
-  :raises: ValueError if descriptors contain more than one descriptor type
+  :returns: **str** of the CSV for the descriptors, one per line
+  :raises: **ValueError** if descriptors contain more than one descriptor type
   """
   
   if isinstance(descriptors, stem.descriptor.Descriptor):
diff --git a/stem/descriptor/reader.py b/stem/descriptor/reader.py
index 809015a..e3d29c5 100644
--- a/stem/descriptor/reader.py
+++ b/stem/descriptor/reader.py
@@ -52,10 +52,10 @@ and picks up where it left off if ran again...
 
 ::
 
-  load_processed_files - Loads a listing of processed files.
-  save_processed_files - Saves a listing of processed files.
+  load_processed_files - Loads a listing of processed files
+  save_processed_files - Saves a listing of processed files
   
-  DescriptorReader - Iterator for descriptor data on the local file system.
+  DescriptorReader - Iterator for descriptor data on the local file system
     |- get_processed_files - provides the listing of files that we've processed
     |- set_processed_files - sets our tracking of the files we have processed
     |- register_skip_listener - adds a listener that's notified of skipped files
@@ -64,12 +64,12 @@ and picks up where it left off if ran again...
     |- __enter__ / __exit__ - manages the descriptor reader thread in the context
     +- __iter__ - iterates over descriptor data in unread files
   
-  FileSkipped - Base exception for a file that was skipped.
-    |- AlreadyRead - We've already read a file with this last modified timestamp.
-    |- ParsingFailure - Contents can't be parsed as descriptor data.
-    |- UnrecognizedType - File extension indicates non-descriptor data.
-    +- ReadFailed - Wraps an error that was raised while reading the file.
-       +- FileMissing - File does not exist.
+  FileSkipped - Base exception for a file that was skipped
+    |- AlreadyRead - We've already read a file with this last modified timestamp
+    |- ParsingFailure - Contents can't be parsed as descriptor data
+    |- UnrecognizedType - File extension indicates non-descriptor data
+    +- ReadFailed - Wraps an error that was raised while reading the file
+       +- FileMissing - File does not exist
 """
 
 from __future__ import with_statement