Updated API reference docs for system descriptions (#298)

* updated docstrings

* updated PackageDatabase docstring

* added missing type to docstring

* fix bad formatting

* updated docstring and encoding

* hide from_dict, to_dict, and from_file for SystemDescription

* updated docstring for SystemDescription

* updated docstring

* added docstring to FormatDatabase

Author: ChrisTimperley

src/roswire/definitions/format.py

@@ -13,8 +13,25 @@
 
 
 class FormatDatabase:
+    """
+    An immutable database of ROS definitions that maintains the parsed
+    contents of :code:`.msg`, :code:`.srv`, and :code:`.action` files
+    for messages, services, and action definitions.
+    Note that implicit message definitions, i.e., those associated with a
+    service or action definition, are also represented by the database.
+
+    Attributes
+    ----------
+    messages: Mapping[str, MsgFormat]
+        An immutable mapping from message name to its definition.
+    services: Mapping[str, SrvFormat]
+        An immutable mapping from service name to definition.
+    actions: Mapping[str, ActionFormat]
+        An immutable mapping from action name to definition.
+    """
     @staticmethod
     def build(db: PackageDatabase) -> 'FormatDatabase':
+        """Constructs a format database from a given package database."""
         messages: Set[MsgFormat] = set()
         services: Set[SrvFormat] = set()
         actions: Set[ActionFormat] = set()

src/roswire/definitions/package.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 __all__ = ('Package', 'PackageDatabase')
 
 from typing import (Tuple, List, Dict, Union, Any, Iterator, Collection,
@@ -23,9 +24,7 @@ class Package:
 
     @staticmethod
     def build(path: str, files: FileProxy) -> 'Package':
-        """
-        Constructs a description of a package located at a given path.
-        """
+        """Constructs a description of a package at a given path."""
         name: str = os.path.basename(path)
         messages: List[MsgFormat] = []
         services: List[SrvFormat] = []
@@ -82,12 +81,23 @@ def to_dict(self) -> Dict[str, Any]:
 
 
 class PackageDatabase(Mapping[str, Package]):
+    """
+    An immutable database of packages, represented as :class:`Package`
+    instances, indexed by their names, given as :class:`str`.
+
+    Note
+    ----
+        Implements most :class:`dict` operations via
+        :class:`abc.collections.Mapping`,
+        including :code:`db['name']`, :code:`len(db)`), :code:`db.keys()`,
+        :code:`db.values()`, and :code:`iter(db)`.
+        As instances of this class are immutable, no destructive
+        :class:`dict` operations are provided (e.g., :code:`del db['foo'])`
+        and `db['foo'] = bar`).
+    """
     @staticmethod
     def paths(shell: ShellProxy, files: FileProxy) -> List[str]:
-        """
-        Parses the contents of the ROS_PACKAGE_PATH environment variable for a
-        given shell.
-        """
+        """Parses :code:`ROS_PACKAGE_PATH` for a given shell."""
         path_str = shell.environ('ROS_PACKAGE_PATH')
         package_paths: List[str] = path_str.strip().split(':')
         paths: List[str] = []
@@ -110,9 +120,20 @@ def from_paths(files: FileProxy,
         Constructs a package database from a list of the paths of the packages
         belonging to the database.
 
-        Parameters:
-            files: access to the filesystem.
-            paths: a list of the absolute paths of the packages.
+        Parameters
+        ----------
+        files: FileProxy
+            access to the filesystem.
+        paths: List[str]
+            a list of the absolute paths of the packages.
+        ignore_bad_paths: bool
+            If :code:`True`, non-existent paths will be ignored.
+            If :code:`False`, a :exc:`FileNotFoundError` will be raised.
+
+        Raises
+        ------
+        FileNotFoundError
+            if no package is found at a given path.
         """
         packages: List[Package] = []
         for p in paths:
@@ -128,17 +149,16 @@ def __init__(self, packages: Collection[Package]) -> None:
         self.__contents = {p.name: p for p in packages}
 
     def __len__(self) -> int:
-        """
-        Returns a count of the number of packages within this database.
-        """
+        """Returns the number of packages within this database."""
         return len(self.__contents)
 
     def __getitem__(self, name: str) -> Package:
-        """
-        Fetches the description for a given package.
+        """Fetches the description for a given package.
 
-        Raises:
-            KeyError: if no package exists with the given name.
+        Raises
+        ------
+        KeyError
+            if no package exists with the given name.
         """
         return self.__contents[name]
 

src/roswire/definitions/type_db.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 __all__ = ('TypeDatabase',)
 
 from typing import (Collection, Type, Mapping, Iterator, Dict, ClassVar, Any,
@@ -25,6 +26,15 @@
 
 
 class TypeDatabase(Mapping[str, Type[Message]]):
+    """
+    An immutable database of ROS types, represented as :class:`Message`
+    subclasses, indexed by the fully qualified names of those types.
+
+    Note
+    ----
+    Implements the set of non-destructive :class:`dict` operations as
+    :class:`PackageDatabase`.
+    """
     @classmethod
     def build(cls, db_format: FormatDatabase) -> 'TypeDatabase':
         formats = list(db_format.messages.values())

src/roswire/description.py

@@ -25,19 +25,20 @@
 @attr.s(slots=True)
 class SystemDescription:
     """
-    A description of the packages, types, and specifications within
-    a containerised ROS application.
+    An immutable description of all of the packages, types, and
+    specifications (i.e., :code:`.msg`, :code:`.srv`, and :code:`.action`
+    files) within a containerised ROS application.
 
     Attributes
     ----------
-        sha256: str
-            The ID of the Docker image for the application.
-        types: TypeDatabase
-            A database of types for the application.
-        formats: FormatDatabase
-            A database of message, service and action specifications.
-        packages:
-            A database of the packages contained within the application.
+    sha256: str
+        The ID of the Docker image for the application.
+    types: TypeDatabase
+        A database of types for the application.
+    formats: FormatDatabase
+        A database of message, service and action specifications.
+    packages: PackageDatabase
+        A database of the packages contained within the application.
     """
     sha256: str = attr.ib()
     types: TypeDatabase = attr.ib()
@@ -46,14 +47,12 @@ class SystemDescription:
 
     @staticmethod
     def from_file(fn: str) -> 'SystemDescription':
-        """Loads a description from a given file."""
         with open(fn, 'r') as f:
             d = yaml.safe_load(f)
         return SystemDescription.from_dict(d)
 
     @staticmethod
     def from_dict(d: Dict[str, Any]) -> 'SystemDescription':
-        """Constructs a description from a JSON dictionary."""
         sha256: str = d['sha256']
         packages = PackageDatabase.from_dict(d['packages'])
         formats = FormatDatabase.build(packages)
@@ -64,7 +63,6 @@ def from_dict(d: Dict[str, Any]) -> 'SystemDescription':
                                  types=types)
 
     def to_dict(self) -> Dict[str, Any]:
-        """Produces a JSON dictionary for this description."""
         return {'sha256': self.sha256,
                 'packages': self.packages.to_dict()}
 
@@ -110,7 +108,7 @@ def load(self,
 
         Raises
         ------
-        FileNotFoundError:
+        FileNotFoundError
             if no description for the given image is stored on disk.
         """
         sha256 = self.__containers.image_sha256(image_or_tag)
@@ -123,9 +121,7 @@ def load(self,
             raise
 
     def saved(self, image_or_tag: Union[str, DockerImage]) -> bool:
-        """
-        Determines whether a description for a given image has been saved.
-        """
+        """Determines whether a description for an image has been saved."""
         sha256 = self.__containers.image_sha256(image_or_tag)
         fn = os.path.join(self.__dir_cache, sha256)
         return os.path.exists(fn)
@@ -145,6 +141,12 @@ def build(self,
         Builds a description of the ROS application contained within a given
         image and optionally saves that description to disk.
 
+        Parameters
+        ----------
+        image_or_tag: Union[str, DockerImage]
+            The name or object for the Docker image.
+        save: bool
+            If :code:`True`, the description will be saved to disk.
 
         Returns
         -------