Add Sphinx documentation.

To get the argparse docs required moving most of the install
script to a module, which probably should have been done anyway.

Author: mikepurvis

doc/conf.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+
+import sys
+import os
+
+#sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'src')))
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.viewcode',
+    'sphinxarg.ext'
+]
+
+# Document constructors (off by default)
+autoclass_content = 'both'
+
+templates_path = ['_templates']
+
+source_suffix = '.rst'
+
+master_doc = 'index'
+
+project = u'robot_upstart'
+copyright = u'2015, Mike Purvis'
+
+# Get version number from package.xml.
+import xml.etree.ElementTree as etree
+tree = etree.parse('../package.xml')
+version = tree.find("version").text
+release = version
+
+pygments_style = 'sphinx'
+
+html_theme = 'nature'
+
+htmlhelp_basename = 'robot_upstartdoc'

doc/index.rst

@@ -0,0 +1,69 @@
+Upstart for ROS Robots
+======================
+
+This package aims to assist with creating simple platform-specific jobs
+to start your robot's ROS launch files when its PC powers up.
+
+.. toctree::
+    :hidden:
+
+    install
+    jobs
+    providers
+
+
+Usage
+-----
+
+The basic or one-off usage is with the ``install`` script, which can be
+as simple as:
+
+.. code-block:: bash
+
+    $ rosrun robot_upstart install myrobot_bringup/launch/base.launch
+
+This will create a job called ``myrobot`` on your machine, which launches
+base.launch. It will start automatically when you next start your machine,
+or you can bring it up and down manually:
+
+.. code-block:: bash
+
+    $ sudo service myrobot start
+    $ sudo service myrobot stop
+
+If the job is crashing on startup, or you otherwise want to see what is
+being output to the terminal on startup, check the upstart log:
+
+.. code-block:: bash
+
+    $ sudo tail /var/log/upstart/myrobot.log -n 30
+
+For more details, please see :doc:`install`.
+
+
+Python API
+----------
+
+More advanced users or platform maintainers will prefer to script the
+job creation as part of a larger installation script which may do other
+tasks, such as pick and choose which launchers to install based on a
+recipe, interactive wizard, or hardware introspection scheme.
+
+These users will want to work with the Python API, which is detailed 
+in :doc:`jobs`.
+
+
+Extending
+---------
+
+If you're interesting in adding support for other init schemes to
+robot_upstart, please see :doc:`providers`.
+
+
+Indexes
+-------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

doc/install.rst

@@ -0,0 +1,7 @@
+The ``install`` script
+======================
+
+.. argparse::
+   :module: robot_upstart.install_script
+   :func: get_argument_parser
+   :prog: install

doc/jobs.rst

@@ -0,0 +1,5 @@
+Jobs
+====
+
+.. autoclass:: robot_upstart.Job
+    :members:

doc/providers.rst

@@ -0,0 +1,5 @@
+Providers
+=========
+
+.. automodule:: robot_upstart.providers
+    :members:

rosdoc.yaml

@@ -0,0 +1,2 @@
+- builder: sphinx
+  sphinx_root_dir: doc

scripts/install

@@ -26,73 +26,7 @@
 The is the main CLI interface to the robot_upstart package.
 """
 
-import argparse
-import os
-
-import robot_upstart
-from catkin.find_in_workspaces import find_in_workspaces
-
-
-def get_argument_parser():
-    p = argparse.ArgumentParser(description=
-        """Use this tool to quickly and easily create system startup jobs
-        which run one or more ROS launch files as a daemonized background
-        process on your computer. More advanced users will prefer to access
-        the Python API from their own setup scripts, but this exists as a
-        simple helper, an example, and a compatibility shim for previous
-        versions of robot_upstart which were bash-based.""")
-
-    p.add_argument("pkgpath", type=str, nargs=1, metavar=("pkg/path",),
-            help="Package and path to install job launch files from.")
-    p.add_argument("--job", type=str,
-            help="Specify job name. If unspecified, will be constructed from package name.")
-    p.add_argument("--interface", type=str, metavar="ethN",
-            help="Specify network interface name to associate job with.")
-    p.add_argument("--user", type=str, metavar="NAME",
-            help="Specify user to launch job as.")
-    p.add_argument("--setup", type=str, metavar="path/to/setup.bash",
-            help="Specify workspace setup file for the job launch context.")
-    p.add_argument("--rosdistro", type=str, metavar="DISTRO",
-            help="Specify ROS distro this is for.")
-    p.add_argument("--master", type=str, metavar="http://MASTER:11311",
-            help="Specify an alternative ROS_MASTER_URI for the job launch context.")
-    p.add_argument("--logdir", type=str, metavar="path/to/logs",
-            help="Specify an a value for ROS_LOG_DIR in the job launch context.")
-    p.add_argument("--augment",
-            help="Bypass creating the job, and only copy user files. Assumes the job was previously created.")
-    return p
-
-
-def main():
-    args = get_argument_parser().parse_args()
-
-    pkg, pkgpath = args.pkgpath[0].split('/', 1)
-    job_name = args.job or pkg.split('_', 1)[0]
-    
-    # Any unspecified arguments are on the args object as None. These are filled
-    # in by the Job constructor when passed as Nones.
-    j = robot_upstart.Job(name=job_name, interface=args.interface, user=args.user,
-            workspace_setup=args.setup, rosdistro=args.rosdistro,
-            master_uri=args.master, log_path=args.logdir)
-
-    found_path = find_in_workspaces(project=pkg, path=pkgpath, first_match_only=True)
-    if not found_path:
-        print "Unable to located path %s in package %s. Installation aborted." % (pkgpath, pkg)
-
-    if os.path.isfile(found_path[0]):
-        # Single file, install just that.
-        j.add(package=pkg, filename=pkgpath)
-    else:
-        # Directory found, install everything within.
-        j.add(package=pkg, glob=os.path.join(pkgpath, "*"))
-
-    if args.augment:
-        j.generate_system_files = False
-
-    j.install()
-
-    return 0;
-
+from robot_upstart.install_script import main
 
 if __name__ == "__main__":
     exit(main())

src/robot_upstart/install_script.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python
+# Software License Agreement (BSD) 
+#
+# @author    Mike Purvis <[email protected]>
+# @copyright (c) 2015, Clearpath Robotics, Inc., All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification, are permitted provided that
+# the following conditions are met:
+# * Redistributions of source code must retain the above copyright notice, this list of conditions and the
+#   following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
+#   following disclaimer in the documentation and/or other materials provided with the distribution.
+# * Neither the name of Clearpath Robotics nor the names of its contributors may be used to endorse or
+#   promote products derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
+# WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+
+import argparse
+import os
+
+import robot_upstart
+from catkin.find_in_workspaces import find_in_workspaces
+
+
+def get_argument_parser():
+    p = argparse.ArgumentParser(description=
+        """Use this tool to quickly and easily create system startup jobs
+        which run one or more ROS launch files as a daemonized background
+        process on your computer. More advanced users will prefer to access
+        the Python API from their own setup scripts, but this exists as a
+        simple helper, an example, and a compatibility shim for previous
+        versions of robot_upstart which were bash-based.""")
+
+    p.add_argument("pkgpath", type=str, nargs=1, metavar=("pkg/path",),
+            help="Package and path to install job launch files from.")
+    p.add_argument("--job", type=str,
+            help="Specify job name. If unspecified, will be constructed from package name.")
+    p.add_argument("--interface", type=str, metavar="ethN",
+            help="Specify network interface name to associate job with.")
+    p.add_argument("--user", type=str, metavar="NAME",
+            help="Specify user to launch job as.")
+    p.add_argument("--setup", type=str, metavar="path/to/setup.bash",
+            help="Specify workspace setup file for the job launch context.")
+    p.add_argument("--rosdistro", type=str, metavar="DISTRO",
+            help="Specify ROS distro this is for.")
+    p.add_argument("--master", type=str, metavar="http://MASTER:11311",
+            help="Specify an alternative ROS_MASTER_URI for the job launch context.")
+    p.add_argument("--logdir", type=str, metavar="path/to/logs",
+            help="Specify an a value for ROS_LOG_DIR in the job launch context.")
+    p.add_argument("--augment",
+            help="Bypass creating the job, and only copy user files. Assumes the job was previously created.")
+    return p
+
+
+def main():
+    args = get_argument_parser().parse_args()
+
+    pkg, pkgpath = args.pkgpath[0].split('/', 1)
+    job_name = args.job or pkg.split('_', 1)[0]
+    
+    # Any unspecified arguments are on the args object as None. These are filled
+    # in by the Job constructor when passed as Nones.
+    j = robot_upstart.Job(name=job_name, interface=args.interface, user=args.user,
+            workspace_setup=args.setup, rosdistro=args.rosdistro,
+            master_uri=args.master, log_path=args.logdir)
+
+    found_path = find_in_workspaces(project=pkg, path=pkgpath, first_match_only=True)
+    if not found_path:
+        print "Unable to located path %s in package %s. Installation aborted." % (pkgpath, pkg)
+
+    if os.path.isfile(found_path[0]):
+        # Single file, install just that.
+        j.add(package=pkg, filename=pkgpath)
+    else:
+        # Directory found, install everything within.
+        j.add(package=pkg, glob=os.path.join(pkgpath, "*"))
+
+    if args.augment:
+        j.generate_system_files = False
+
+    j.install()
+
+    return 0;

src/robot_upstart/providers.py

@@ -36,12 +36,30 @@
 
 
 class Generic(object):
+    """ Provides only a common constructor for the moment, but as further
+        providers are implemented, may provide a place to store configuration
+        common to them. """
+
     def __init__(self, root, job):
+        """ Construct a new Provider.
+
+        :param root: The filesystem location to prefix all file-install
+            commands with.
+        :type root: str
+        :param job: The job definition to transform to a set of system files.
+        :type job: :py:class:robot_upstart.Job
+        """
         self.root = root
         self.job = job
 
 
 class Upstart(Generic):
+    """ The Upstart implementation places the user-specified files in ``/etc/ros/DISTRO/NAME.d``,
+    and creates an upstart job configuration in ``/etc/init/NAME.d``. Two additional
+    helper scripts are created for starting and stopping the job, places in
+    ``/usr/sbin``.
+    """
+
     def generate(self):
         self.job.job_path = os.path.join(self.root, "etc/ros",
                 self.job.rosdistro, self.job.name + ".d")