Added API docs for ROS core, nodes, and services (#299)

* updated docstring

* added topic_to_type docstring

* improved docstring for record

* updated docstring for playback

* added ROS section to docs

* added docstring to node

* updated docstring for __getitem__

* documented node manager

* added docstring to node manager

* added import and removed excess whitespace

* updated service docstrings

* added returns to docstring

* updated node docstring

* added services to API ref docs

Author: ChrisTimperley

docs/api.rst

@@ -8,7 +8,7 @@ the roswire library.
 
 .. py:module:: roswire
 .. autoclass:: ROSWire
-  :members:
+   :members:
 
 
 System
@@ -26,6 +26,40 @@ with a :code:`bash` shell inside the application container.
   :members:
 
 
+ROS
+---
+
+.. py:module:: roswire.proxy
+.. autoclass:: ROSProxy()
+  :members:
+
+.. autoclass:: NodeManagerProxy()
+  :show-inheritance:
+  :members:
+  :inherited-members:
+
+  .. automethod:: __getitem__
+  .. automethod:: __delitem__
+  .. automethod:: __iter__
+  .. automethod:: __len__
+
+.. autoclass:: NodeProxy()
+   :members:
+
+.. autoclass:: ServiceManagerProxy()
+  :show-inheritance:
+  :members:
+  :inherited-members:
+
+  .. automethod:: __getitem__
+  .. automethod:: __delitem__
+  .. automethod:: __iter__
+  .. automethod:: __len__
+
+.. autoclass:: ServiceProxy()
+   :members:
+
+
 Shell
 -----
 
@@ -42,7 +76,7 @@ Filesystem
 
 .. py:module:: roswire.proxy.file
 .. autoclass:: FileProxy()
-   :members:
+  :members:
 
 
 Descriptions

src/roswire/proxy/__init__.py

@@ -5,6 +5,7 @@
     'ParameterServerProxy',
     'NodeManagerProxy',
     'NodeProxy',
+    'ServiceProxy',
     'ROSProxy',
     'BagRecorderProxy',
     'BagPlayerProxy',
@@ -31,7 +32,7 @@
 from .parameters import ParameterServerProxy
 from .bag import BagRecorderProxy, BagPlayerProxy
 from .node import NodeProxy, NodeManagerProxy
-from .service import ServiceManagerProxy
+from .service import ServiceProxy, ServiceManagerProxy
 from ..description import SystemDescription
 from ..exceptions import ROSWireException
 
@@ -40,7 +41,23 @@
 
 
 class ROSProxy:
-    """Provides access to a remote ROS master via XML-RPC."""
+    """Provides access to a remote ROS master via XML-RPC.
+
+    Attributes
+    ----------
+    uri: str
+        The URI of the ROS Master.
+    connection: xmlrpc.client.ServerProxy
+        The XML-RPC connection to the ROS master.
+    nodes: NodeManagerProxy
+        Provides access to the nodes running on this ROS Master.
+    services: ServiceManagerProxy
+        Provides access to the services advertised on this ROS Master.
+    parameters: ParameterServerProxy
+        Provides access to the parameter server for this ROS Master.
+    topic_to_type: Dict[str, str]
+        A mapping from topic names to the names of their message types.
+    """
     def __init__(self,
                  description: SystemDescription,
                  shell: ShellProxy,
@@ -71,29 +88,20 @@ def __init__(self,
                                 self.__connection,
                                 self.__shell)
 
-    @property
-    def uri(self) -> str:
-        """The URI of the ROS Master."""
-        return self.__uri
-
     @property
     def nodes(self) -> NodeManagerProxy:
-        """Provides access to the nodes running on this ROS master."""
         return self.__nodes
 
     @property
     def services(self) -> ServiceManagerProxy:
-        """Provides access to the services advertised on this ROS master."""
         return self.__services
 
     @property
     def parameters(self) -> ParameterServerProxy:
-        """Provides access to the parameter server for this ROS Master."""
         return self.__parameters
 
     @property
     def connection(self) -> xmlrpc.client.ServerProxy:
-        """The XML-RPC connection to the ROS master."""
         return self.__connection
 
     @property
@@ -116,7 +124,8 @@ def launch(self,
         Parameters
         ----------
         filename: str
-            The name of the launch file (or an absolute path).
+            The name of the launch file, or an absolute path to the launch
+            file inside the container.
         package: str, optional
             The name of the package to which the launch file belongs.
         args: Dict[str, Union[int, str]], optional
@@ -141,7 +150,26 @@ def record(self,
                fn: str,
                exclude_topics: Optional[Collection[str]] = None
                ) -> BagRecorderProxy:
-        """Provides an interface to rosbag for recording ROS topics."""
+        """Provides an interface to rosbag for recording ROS topics to disk.
+
+        Note
+        ----
+            This method records bag files to the host machine, and not to the
+            container where the ROS instance is running.
+
+        Parameters
+        ----------
+        fn: str
+            The name of the file, on the host machine, to which the bag should
+            be recorded
+        exclude_topics: Collection[str], optional
+            An optional collection of topics that should not be recorded.
+
+        Returns
+        -------
+        BagRecorderProxy
+            An interface for dynamically interacting with the bag recorder.
+        """
         return BagRecorderProxy(fn,
                                 self.__ws_host,
                                 self.__shell,
@@ -153,7 +181,22 @@ def playback(self,
                  *,
                  file_on_host: bool = True
                  ) -> BagPlayerProxy:
-        """Provides an interface to rosbag for replaying bag files."""
+        """Provides an interface to rosbag for replaying bag files from disk.
+
+        Parameters
+        ----------
+        fn: str
+            The bag file that should be replayed.
+        file_on_host: bool
+            If :code:`True`, as by default, :code:`fn` will be considered to
+            be a file on the host machine. If :code:`False`, :code:`fn` will
+            be considered to be a file inside the container.
+
+        Returns
+        -------
+        BagPlayerProxy
+            An interface for dynamically controlling the bag player.
+        """
         fn_ctr: str
         delete_file_after_use: bool = False
         if file_on_host:

src/roswire/proxy/node.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 __all__ = ('NodeManagerProxy', 'NodeProxy')
 
 from typing import Iterator, Set, Mapping, Optional
@@ -15,42 +16,45 @@
 
 
 class NodeProxy:
+    """Provides access to a ROS node.
+
+    Attributes
+    ----------
+    api: xmlrpc.client.ServerProxy
+        An XML-RPC API client for this node.
+    name: str
+        The fully qualified name of this node.
+    url: str
+        URL used to access this node from the host network.
+    pid: int
+        The container PID of the main process for this node.
+    pid_host: int
+        The host PID of the main process for this node.
+    """
     def __init__(self,
                  name: str,
                  url_host_network: str,
                  shell: ShellProxy
                  ) -> None:
-        """
-        Constructs a proxy for a given name.
-
-        Parameters:
-            name: the name of the node.
-            url_host_network: the URL of the node on the host network.
-            shell: a shell proxy.
-        """
         self.__name = name
         self.__url = url_host_network
         self.__shell = shell
         self.__pid_host: Optional[int] = None
 
     @property
     def api(self) -> xmlrpc.client.ServerProxy:
-        """Provides access to the XML-RPC API for this node."""
         return xmlrpc.client.ServerProxy(self.url)
 
     @property
     def name(self) -> str:
-        """The fully qualified name of this node."""
         return self.__name
 
     @property
     def url(self) -> str:
-        """URL used to access this node from the host network."""
         return self.__url
 
     @property
     def pid(self) -> int:
-        """The container PID of the main process for this node."""
         code, status, pid = self.api.getPid('/.roswire')
         if code != 1:
             m = f"failed to obtain PID [{self.name}]: {status} (code: {code})"
@@ -61,24 +65,26 @@ def pid(self) -> int:
 
     @property
     def pid_host(self) -> int:
-        """The host PID of the main process for this node."""
         if self.__pid_host is None:
             self.__pid_host = self.__shell.local_to_host_pid(self.pid)
             assert self.__pid_host is not None
         return self.__pid_host
 
     def is_alive(self) -> bool:
+        """Determines whether this node is alive."""
         # TODO check start time to ensure this is the same process!
         try:
             return psutil.pid_exists(self.pid_host)
         except ROSWireException:
             return False
 
     def shutdown(self) -> None:
+        """Instructs this node to shutdown."""
         self.__shell.execute(f'rosnode kill {self.name}')
 
 
 class NodeManagerProxy(Mapping[str, NodeProxy]):
+    """Provides access to all nodes on a ROS graph."""
     def __init__(self,
                  host_ip_master: str,
                  api: xmlrpc.client.ServerProxy,
@@ -104,23 +110,30 @@ def __get_node_names(self) -> Set[str]:
         return names
 
     def __len__(self) -> int:
-        """
-        Returns a count of the number of active nodes.
-        """
+        """Returns a count of the number of active nodes."""
         return len(self.__get_node_names())
 
     def __iter__(self) -> Iterator[str]:
-        """
-        Returns an iterator over the names of all active nodes.
-        """
+        """Returns an iterator over the names of all active nodes."""
         yield from self.__get_node_names()
 
     def __getitem__(self, name: str) -> NodeProxy:
-        """
-        Attempts to fetch a given node.
-
-        Raises:
-            NodeNotFoundError: if there is no node with the given name.
+        """Attempts to fetch a given node.
+
+        Parameters
+        ----------
+        name: str
+            The name of the node.
+
+        Returns
+        -------
+        NodeProxy
+            An interface to the given node.
+
+        Raises
+        ------
+        NodeNotFoundError
+            If there is no node with the given name.
         """
         code, status, uri_container = self.api.lookupNode('/.roswire', name)
         if code == -1:
@@ -135,11 +148,17 @@ def __getitem__(self, name: str) -> NodeProxy:
         return NodeProxy(name, uri_host, self.__shell)
 
     def __delitem__(self, name: str) -> None:
-        """
-        Shutdown and deregister a given node.
+        """Shutdown and deregister a given node.
+
+        Parameters
+        ----------
+        name: str
+            The name of the node.
 
-        Raises:
-            NodeNotFoundError: no node found with given name.
+        Raises
+        ------
+        NodeNotFoundError
+            no node found with given name.
         """
         try:
             node = self[name]