From 022b0c2882dd669160dbb7053ed630cdd00ee9fe Mon Sep 17 00:00:00 2001
From: Martin Baeuml <baeuml@kit.edu>
Date: Tue, 7 Jun 2011 16:47:30 +0200
Subject: [PATCH] add container API reference

---
 doc/api/containers.rst         | 25 +++++++++++++++++++++++++
 doc/{api.rst => api/index.rst} | 12 +++++++++---
 doc/index.rst                  |  2 +-
 sloth/annotations/container.py | 34 ++++++++++++++++++++++++++++++----
 4 files changed, 65 insertions(+), 8 deletions(-)
 create mode 100644 doc/api/containers.rst
 rename doc/{api.rst => api/index.rst} (93%)

diff --git a/doc/api/containers.rst b/doc/api/containers.rst
new file mode 100644
index 0000000..830affc
--- /dev/null
+++ b/doc/api/containers.rst
@@ -0,0 +1,25 @@
+==========
+Containers
+==========
+
+.. module:: sloth.annotations.container
+
+This details the default containers that come with sloth.
+
+The following containers are available in :mod:`sloth.annotations.container`:
+
+.. automodule:: sloth.annotations.container
+.. autoclass:: AnnotationContainer
+    :members:
+
+.. autoclass:: JsonContainer
+    :members:
+
+.. autoclass:: YamlContainer
+    :members:
+
+.. autoclass:: PickleContainer
+    :members:
+
+.. autoclass:: FeretContainer
+    :members:
diff --git a/doc/api.rst b/doc/api/index.rst
similarity index 93%
rename from doc/api.rst
rename to doc/api/index.rst
index 0f1d061..5888c0e 100644
--- a/doc/api.rst
+++ b/doc/api/index.rst
@@ -1,9 +1,15 @@
-===
-API
-===
+=============
+API Reference
+=============
 
 .. todo:: Actually document the code, so that this is not just a bunch of method names.
 
+.. toctree::
+   :maxdepth: 1
+
+   containers
+   models
+
 annotationmodel
 ===============
 
diff --git a/doc/index.rst b/doc/index.rst
index 8de26de..596485c 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -40,7 +40,7 @@ Contents
    items
    inserters
    containers
-   api
+   api/index
 
 
 TODOs
diff --git a/sloth/annotations/container.py b/sloth/annotations/container.py
index 54bfdc6..6f52599 100644
--- a/sloth/annotations/container.py
+++ b/sloth/annotations/container.py
@@ -70,7 +70,7 @@ class AnnotationContainer:
 
     def load(self, filename):
         """
-        Load the annotations.  Must be implemented in the subclass.
+        Load the annotations.
         """
         self.annotations_ = self.parseFromFile(filename)
         self.filename_ = filename
@@ -87,7 +87,7 @@ class AnnotationContainer:
 
     def save(self, filename):
         """
-        Save the annotations.  Must be implemented in the subclass.
+        Save the annotations.
         """
         self.serializeToFile(filename)
         self.filename_ = filename
@@ -103,11 +103,14 @@ class AnnotationContainer:
         )
 
     def setAnnotations(self, annotations):
+        """
+        Set the current annotations. Expects a list of python dictionaries.
+        """
         self.annotations_ = annotations
 
     def annotations(self):
         """
-        Returns the current annotations as python dictionary.
+        Returns the current annotations as list of python dictionaries.
         """
         return self.annotations_
 
@@ -164,10 +167,16 @@ class PickleContainer(AnnotationContainer):
     """
 
     def parseFromFile(self, fname):
+        """
+        Overwritten to read pickle files.
+        """
         f = open(fname, "rb")
         return pickle.load(f)
 
     def serializeToFile(self, fname):
+        """
+        Overwritten to write pickle files.
+        """
         # TODO make all image filenames relative to the label file
         f = open(fname, "wb")
         pickle.dump(self.annotations(), f)
@@ -179,10 +188,16 @@ class JsonContainer(AnnotationContainer):
     """
 
     def parseFromFile(self, fname):
+        """
+        Overwritten to read JSON files.
+        """
         f = open(fname, "r")
         return json.load(f)
 
     def serializeToFile(self, fname):
+        """
+        Overwritten to write JSON files.
+        """
         # TODO make all image filenames relative to the label file
         f = open(fname, "w")
         json.dump(self.annotations(), f, indent=4)
@@ -194,10 +209,16 @@ class YamlContainer(AnnotationContainer):
     """
 
     def parseFromFile(self, fname):
+        """
+        Overwritten to read YAML files.
+        """
         f = open(fname, "r")
         return yaml.load(f)
 
     def serializeToFile(self, fname):
+        """
+        Overwritten to write YAML files.
+        """
         # TODO make all image filenames relative to the label file
         f = open(fname, "w")
         yaml.dump(self.annotations(), f)
@@ -209,7 +230,9 @@ class FeretContainer(AnnotationContainer):
     """
 
     def parseFromFile(self, filename):
-        self.basedir_ = os.path.dirname(filename)
+        """
+        Overwritten to read Feret label files.
+        """
         f = open(filename)
 
         annotations = []
@@ -232,6 +255,9 @@ class FeretContainer(AnnotationContainer):
         return annotations
 
     def serializeToFile(self, filename):
+        """
+        Not implemented yet.
+        """
         # TODO make sure the image paths are
         # relative to the label file's directory
         raise NotImplemented(