Add documentation that already exists on the wiki.\nAdd some new...

Add documentation that already exists on the wiki.\nAdd some new documentation.\nAdd a new extension for linking to ROS documentation.

docs/src/main/sphinx/best_practices.rst

+Best practices
+==============
+
+rosjava is different than other ROS client libraries in many respects. As a
+result, there are new best practices that should be followed while developing a
+rosjava application.
+
+Java package names
+------------------
+
+As usual, Java package names should start with a reversed domain name. In the
+ROS ecosystem, the domain name should be followed by the ROS package name. For
+example:
+
+- org.ros.rosjava
+- org.ros.rosjava_geometry
+
+Only core packages (e.g. those in rosjava_core and android_core) should being
+with org.ros.
+

docs/src/main/sphinx/building.rst

 Building rosjava_core
 =====================
 
-rosjava_core uses the `Gradle`_ build system. To build rosjava_core, execute the `gradle wrapper`_:
+rosjava_core uses the `Gradle`_ build system. `rosmake`_ is not supported.
+
+To build rosjava_core, execute the `gradle wrapper`_:
 
 .. _Gradle: http://www.gradle.com/
+.. _rosmake: http://ros.org/wiki/rosmake/
 .. _gradle wrapper: http://gradle.org/docs/current/userguide/gradle_wrapper.html
 
-Note that the build process currently involves extra steps that will be folded into Gradle tasks.
+Note that the build process currently involves extra steps that will be folded
+into Gradle tasks or otherwise eliminated.
 
+#. `Install Maven 3 <http://maven.apache.org/download.html>`_.
 #. roscd rosjava_core
 #. ./gradlew rosjava_bootstrap:install
 #. rosrun rosjava_bootstrap install_generated_modules.py rosjava
@@ -18,6 +23,7 @@ Then, for each rosjava_core package you're interested in (e.g. foo):
 #. rosrun rosjava_bootstrap install_generated_modules.py foo
 #. ./gradlew foo:install
 
-See the rosjava `Javadoc <javadoc/index.html>`_ to learn more about the API.
+To generate Eclipse project files:
+
+#. ./gradlew foo:eclipse
 
-Note that package level documentation is in progress.

docs/src/main/sphinx/conf.py.in

@@ -25,7 +25,7 @@ needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['javadoc']
+extensions = ['javadoc', 'ros']
 
 javadoc_root = 'javadoc'
 
@@ -84,6 +84,7 @@ exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
+highlight_language = 'java'
 
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []

docs/src/main/sphinx/getting_started.rst

+Getting started
+===============
+
+Creating a new Java package
+---------------------------
+
+Creating nodes
+--------------
+
+Messages
+--------
+
+To import a specific message, you must first declare a dependency on that
+message's package in your :roswiki:`Manifest` file and your build.gradle file.
+
+Note that this redundancy will be removed in the near future.
+
+This will add the message's jar file to your classpath.
+
+Next, to use a message such as :rosmsg:`sensor_msgs/PointCloud2`, simply add an
+import.  Rather than instantiate the message directly, however, it's preferred
+that you use a :javadoc:`org.ros.message.MessageFactory` instead. This helps
+allow the underlying message implementation to change in the future. ::
+
+  import  org.ros.message.sensor_msgs.PointCloud;
+
+  ...
+
+  Node node;
+
+  ...
+
+  PointCloud2 msg = node.getMessageFactory()
+      .newMessage("sensor_msgs/PointCloud");
+
+If you want to use messages that you define:
+
+- create a new package for those messages (e.g. my_msgs)
+- add a dependency on the new package as described above
+- ``rosrun rosjava_bootstrap install_generated_messages.py my_package``
+
+Messages as BLOBs (Advanced)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you need to deserialize a ROS message BLOB, it is important to remember that
+Java is a big endian virtual machine. When supplying the ``ByteBuffer`` to the
+:javadoc:`org.ros.message.MessageDeserializer`, make sure that order is set to
+little endian. ::
+
+  Node node;
+  byte[] messageData;
+
+  ...
+
+  ByteBuffer buffer = ByteBuffer.wrap(messageData);
+  buffer.order(ByteOrder.LITTLE_ENDIAN);
+  PointCloud2 msg = node.getMessageSerializationFactory()
+      .newMessageDeserializer("sensor_msgs/PointCloud")
+          .deserialize(buffer);
+
+Publishers and subscribers
+--------------------------
+
+Services
+--------
+
+Parameters
+----------
+
+rosjava offers full access to the ROS :roswiki:`Parameter Server`. The
+:roswiki:`Parameter Server` is a shared dictionary of configuration parameters
+accessible to all the nodes at runtime. It is meant to store configuration
+parameters that are easy to inspect and modify.
+
+Parameters are accessible via :javadoc:`org.ros.node.parameter.ParameterTree`\s
+(provided by :javadoc:`org.ros.node.Node`\s). ::
+
+  ParameterTree params = node.newParameterTree();
+
+Accessing Parameters
+~~~~~~~~~~~~~~~~~~~~
+
+The :javadoc:`org.ros.node.parameter.ParameterTree` API allows you to set and
+query lists, maps, and single objects of integers, strings and floats.
+
+Unlike typical ROS :roswiki:`Client Libraries`, rosjava requires that the type
+of the parameter be known when you retrieve it. If the actual parameter type
+doesn't match the expected type, an exception will be thrown. ::
+
+  boolean foo = params.getBoolean("/foo");
+  int bar = params.getInteger("/bar", 42 /* default value */);
+  double baz = params.getDouble("/foo/baz");
+
+  params.set("/bloop", "Hello, world!");
+  String helloWorld = params.getString("/bloop");
+
+  List<Integer> numbers = params.getList("/numbers");
+  Map<String, String> strings = params.getMap("/strings");
+
+As with other ROS client libraries, it is possible to retrieve a subtree of
+parameters. However, you will be responsible for casting the values to their
+appropriate types. ::
+
+  Map<String, Object> subtree = params.getMap("/subtree");
+
+Using a ParameterListener
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is also possible to subscribe to a particular parameter using a
+:javadoc:`org.ros.node.parameter.ParameterListener`. Note that this does not
+work for parameter subtrees. ::
+
+  params.addParameterListener("/foo/bar", new ParameterListener() {
+    @Override
+    public void onNewValue(Object value) {
+      ...
+    }
+  });
+
+Currently, ParameterListeners are not generic. Instead, you are responsible for casting value appropriately.
+
+Logging
+-------
+
+The logging interface for rosjava is accessed through
+:javadoc:`org.ros.node.Node` objects via the
+:javadoc:`org.ros.node.Node#getLog()` method. This object returns an `Apache
+Commons Log`_ object which handles the debug, info, error, warning, and fatal
+logging outputs for ROS. ::
+
+  node.getLog.debug("debug message");
+  node.getLog.info(" informative message");
+
+  node.getLog.warn("warning message");
+
+  //report an error message
+  node.getLog.error("error message");
+
+  //error message with an exception
+  //so that it can print the stack trace
+  node.getLog.error("error message", e);
+
+  node.fatal("message informing user of a fatal occurrence");
+
+.. _Apache Commons Log: http://commons.apache.org/logging/commons-logging-1.1.1/apidocs/index.html
+
+Exceptions
+----------
+
+Running nodes
+-------------
+

docs/src/main/sphinx/index.rst

-.. rosjava_core documentation master file, created by
-   sphinx-quickstart on Thu Mar  8 15:07:47 2012.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+rosjava_core
+============
 
-Welcome to rosjava_core's documentation!
-========================================
+rosjava is a pure Java implementation of ROS. It provides a client library that
+enables Java programmers to quickly interface with ROS Topics, Services, and
+Parameters. It also provides a Java implementation of `roscore`_. Using rosjava
+is ideal when you need to:
+
+- interact with prior Java programs or libraries
+- write Android apps that work with ROS
+
+Please see the :doc:`overview` page for documentation on how to use rosjava in your
+projects.
+
+Support is best found on http://answers.ros.org/.
+
+Please file bugs and feature requests on the rosjava `issues`_ page. Starring
+issues that are important to you will help developers prioritize their work.
+
+.. _roscore:  http://ros.org/wiki/roscore
+.. _issues: http://code.google.com/p/rosjava/issues/list
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
+   overview
    building
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   best_practices
+   getting_started
 

docs/src/main/sphinx/javadoc.py

@@ -24,7 +24,8 @@ def make_javadoc_link(name, rawtext, text, lineno, inliner, options={}, content=
   javadoc_root = env.config.javadoc_root
   class_part, method_part = (text.split('#', 1) + [''])[:2]
   refuri = os.path.join(javadoc_root, '%s.html#%s' % (class_part.replace('.', '/'), method_part))
-  node = nodes.reference(rawtext, utils.unescape(text), refuri=refuri, **options)
+  label = text.rsplit('.', 1)[-1].replace('#', '.')
+  node = nodes.reference(rawtext, label, refuri=refuri, **options)
   return [node], []
 
 

docs/src/main/sphinx/overview.rst

+Overview
+========
+
+While rosjava is mostly feature complete, it is currently under active
+development. Consider all APIs and documentation to be volatile.
+
+`Javadoc <javadoc/index.html>`_ is used extensively and cross referenced from
+this documentation.
+
+Note that package level documentation is in progress.
+
+Asynchronous
+------------
+
+Because ROS is heavily dependent on network communication, rosjava is
+asynchronous. No attempt is made to hide asynchronous behavior behind a
+synchronous API. As a result, the rosjava APIs may feel unfamiliar.
+
+First, you will not find a ``spin()`` method. Unlike other client libraries,
+many rosjava nodes can run in a thread pool within a single JVM process. In
+this way, rosjava nodes are similar to C++ nodlets. In the future, rosjava
+nodes will support in memory communication in the same way that C++ nodelets do
+today.
+

docs/src/main/sphinx/ros.py

+# Copyright (C) 2012 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+__author__ = 'damonkohler@google.com (Damon Kohler)'
+
+from docutils import nodes
+
+
+def make_roswiki_link(name, rawtext, text, lineno, inliner, options={}, content=[]):
+  refuri = 'http://ros.org/wiki/' + text
+  node = nodes.reference(rawtext, text, refuri=refuri, **options)
+  return [node], []
+
+
+def make_rosmsg_link(name, rawtext, text, lineno, inliner, options={}, content=[]):
+  package, message = text.split('/', 1)
+  refuri = 'http://ros.org/doc/api/%s/html/msg/%s.html' % (package, message)
+  node = nodes.reference(rawtext, text, refuri=refuri, **options)
+  return [node], []
+
+
+def make_rossrv_link(name, rawtext, text, lineno, inliner, options={}, content=[]):
+  package, message = text.split('/', 1)
+  refuri = 'http://ros.org/doc/api/%s/html/srv/%s.html' % (package, message)
+  node = nodes.reference(rawtext, text, refuri=refuri, **options)
+  return [node], []
+
+
+def setup(app):
+  app.add_role('roswiki', make_roswiki_link)
+  app.add_role('rosmsg', make_rosmsg_link)
+  app.add_role('rossrv', make_rossrv_link)
+