diff --git a/docs/src/main/sphinx/best_practices.rst b/docs/src/main/sphinx/best_practices.rst index ddfb1ac9da9a9ecc53683321e0faf1dba4eabb75..f3c582678e34e09e9fb95d62642bb5e381c941ff 100644 --- a/docs/src/main/sphinx/best_practices.rst +++ b/docs/src/main/sphinx/best_practices.rst @@ -16,5 +16,8 @@ example: - org.ros.rosjava_geometry Only core packages (e.g. those in rosjava_core and android_core) should begin -with org.ros. +with org.ros. A suitably unique choice for github based repos would be +the github url followed organization and repository/package name, e.g. + +- com.github.rosjava.rosjava_extras diff --git a/docs/src/main/sphinx/building.rst b/docs/src/main/sphinx/building.rst index 6ad997c29771259603f4db9acbd2b1da9a92b2f0..46302ca080b0a5a9aa722b3370aae6dd4c6e7c9b 100644 --- a/docs/src/main/sphinx/building.rst +++ b/docs/src/main/sphinx/building.rst @@ -1,16 +1,20 @@ .. _building: -Building rosjava_core -===================== +Building +======== -rosjava_core uses the `Gradle`_ build system. `rosmake`_ is not supported. +Gradle +------ + +rosjava_core uses the `Gradle`_ build system in tandem with an external maven +repository which supplies dependencies. To build rosjava_core and install it to your local `Maven`_ repository, execute the `gradle wrapper`_: .. code-block:: bash - roscd rosjava_core + cd rosjava_core ./gradlew install To build the documentation, you may execute the docs task: @@ -31,8 +35,17 @@ To generate Eclipse project files, you may execute the eclipse: ./gradlew eclipse +Catkin +------ + +It also has a very minimal catkin wrapper that relays build instructions to the +underlying gradle builder. This lets the repository be easily built and +deployed alongside other rosjava repositories in a ros environment. Refer to +the `RosWiki`_ for more information. + + .. _Gradle: http://www.gradle.org/ .. _rosmake: http://ros.org/wiki/rosmake/ .. _Maven: http://maven.apache.org/ .. _gradle wrapper: http://gradle.org/docs/current/userguide/gradle_wrapper.html - +.. _RosWiki: http://wiki.ros.org/rosjava diff --git a/docs/src/main/sphinx/conf.py.in b/docs/src/main/sphinx/conf.py.in index 75bfc5a57a2da7a1fac3689a122612a0020c6bf4..a3b316bbcb66a0a8c691c7e08258b48f70d25ec8 100644 --- a/docs/src/main/sphinx/conf.py.in +++ b/docs/src/main/sphinx/conf.py.in @@ -28,7 +28,7 @@ needs_sphinx = '1.0' extensions = ['sphinx.ext.intersphinx', 'javadoc', 'ros'] intersphinx_mapping = { - 'android-core': ('http://docs.rosjava.googlecode.com/hg/android_core/html/', None), + 'android-core': ('http://rosjava.github.io/android_core/latest/', None), } javadoc_root = 'javadoc' @@ -47,7 +47,7 @@ master_doc = 'index' # General information about the project. project = u'rosjava_core' -copyright = u'2012, Google, Inc.' +copyright = u'2013, Google, Inc.' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/docs/src/main/sphinx/getting_started.rst b/docs/src/main/sphinx/getting_started.rst index 7d7952c36439ed44ee43b19c03f1c6d63976f23b..be78f1c0a6fd519d1b453bf29df593f3afb0e63e 100644 --- a/docs/src/main/sphinx/getting_started.rst +++ b/docs/src/main/sphinx/getting_started.rst @@ -6,60 +6,11 @@ Getting started Creating a new Java package --------------------------- -The following steps will be wrapped up in package creation script in the near -future. - -#. Use ``roscreate-pkg`` to create a new package. See - :roswiki:`ROS/Tutorials/CreatingPackage`. -#. Remove the generated ``Makefile`` and ``CMakeLists.txt`` files. -#. Add a new build.gradle file (see :ref:`build-gradle-example`). -#. Put your your Java sources in ``src/main/java`` and your tests in ``src/test/java``. -#. Assuming you have already completed :doc:`building`, you can now call - ``gradle build`` to build and test your package. - -.. _build-gradle-example: - -build.gradle example -~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: groovy - - apply plugin: 'java' - - // The Maven plugin is only required if your package is used as a library. - apply plugin: 'maven' - - // The Application plugin and mainClassName attribute are only required if - // your package is used as a binary. - apply plugin: 'application' - mainClassName = 'org.ros.RosRun' - - sourceCompatibility = 1.6 - targetCompatibility = 1.6 - - repositories { - mavenLocal() - maven { - url 'http://robotbrains.hideho.org/nexus/content/groups/ros-public' - } - } - - version = '0.0.0-SNAPSHOT' - group = 'ros.my_stack' - - dependencies { - compile 'ros.rosjava_core:rosjava:0.0.0-SNAPSHOT' - } - -If you use the `Maven plugin`_, you may use ``gradle install`` to install your -package to your local .m2 cache and make it available to other rosjava packages -on your system. - -If you use the `Application plugin`_, you may use ``gradle installApp`` to create -an executable wrapper for your package. - -See the Gradle `Java tutorial`_ for more details. +Please refer to the `RosWiki`_ for more information on how to create a new +gradle/catkin project and subprojects. You might also wish to read the +Gradle `Java tutorial`_ for more details. +.. _RosWiki: http://wiki.ros.org/rosjava .. _Maven plugin: http://gradle.org/docs/current/userguide/maven_plugin.html .. _Application plugin: http://gradle.org/docs/current/userguide/application_plugin.html .. _Java tutorial: http://gradle.org/docs/current/userguide/tutorial_java_projects.html diff --git a/docs/src/main/sphinx/index.rst b/docs/src/main/sphinx/index.rst index e50b74e48572212e0b0004f8e9b8db54f808f8f5..e09b1fcf7fec0338fa4607474587be11c006cc57 100644 --- a/docs/src/main/sphinx/index.rst +++ b/docs/src/main/sphinx/index.rst @@ -7,14 +7,13 @@ and Parameters. It also provides a Java implementation of `roscore`_. 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. +Please file bugs and feature requests on the rosjava `issues`_ page. In addition to the following documentation, rosjava_core makes liberal use of `Javadoc`_. .. _roscore: http://ros.org/wiki/roscore -.. _issues: http://code.google.com/p/rosjava/issues/list +.. _issues: https://github.com/rosjava/rosjava_core .. _Javadoc: javadoc/index.html Contents: diff --git a/docs/src/main/sphinx/installing.rst b/docs/src/main/sphinx/installing.rst index 69ea8bff223da5b08bcb66a5eef6f93a05ba21aa..9ac1c5aa58807f39861b36ed4a98083f11b0db75 100644 --- a/docs/src/main/sphinx/installing.rst +++ b/docs/src/main/sphinx/installing.rst @@ -1,39 +1,43 @@ .. _installing: -Installing rosjava_core -======================= +Installing +========== -These instructions assume that you have already installed ROS on your system. -See :roswiki:`ROS/Installation` if you need help installing ROS. +Prerequisites +------------- -These instructions also assume you are using Ubuntu. However, the differences -between platforms should be minimal. +You will need a java implementation - this package has been well tested with openjdk-6, +but is also likely to work equally as well with other implementations (oraclejdk has +also had minimal testing). -The recommend installation procedure is to use rosws. See the `rosws tutorial`_ -for more information if you find the following quick start instructions to be -insufficient. +If you would like to build the rosjava_core documentation, you will also need +Pygments 1.5+ and Sphinx 1.1.3+. If you don't have native binaries, then .. code-block:: bash - sudo apt-get install python-pip - sudo pip install --upgrade rosinstall - mkdir ~/my_workspace - cd ~/my_workspace - rosws init - rosws merge /opt/ros/electric/.rosinstall - rosws merge http://rosjava.googlecode.com/hg/.rosinstall - rosws update - source setup.bash + sudo pip install --upgrade sphinx Pygments + -.. note:: You should source the correct setup script for your shell (e.g. - setup.bash for Bash or setup.zsh for Z shell). +Non-ROS Installation +-------------------- -If you would like to build the rosjava_core documentation, you will also need -Pygments 1.5+ and Sphinx 1.1.3+. +This java package no longer requires a ros environment to be installed. In this case, +you simply need to clone the github repository .. code-block:: bash - sudo pip install --upgrade sphinx Pygments + git clone https://github.com/rosjava/rosjava_core + git checkout -b hydro origin/hydro + +and proceed immediately to the section on :ref:`building`. + +ROS Installation +---------------- + +If you would like a full ros environment backending your installation (you might +be generating code for your own custom messages, sequencing builds of multiple rosjava +repositories or using mixed packages, e.g. java + python) then refer to the `RosWiki`_ +for more details. -.. _rosws tutorial: http://www.ros.org/doc/api/rosinstall/html/rosws_tutorial.html +.. _RosWiki: http://wiki.ros.org/rosjava diff --git a/docs/src/main/sphinx/ros.py b/docs/src/main/sphinx/ros.py index 73e4df5f665fcc4ecfde8f27b46ba4b07d84accc..063d64bb00351f634fb408bf1ad6ce1cab5dc9f5 100644 --- a/docs/src/main/sphinx/ros.py +++ b/docs/src/main/sphinx/ros.py @@ -18,7 +18,7 @@ from docutils import nodes def make_roswiki_link(name, rawtext, text, lineno, inliner, options={}, content=[]): - refuri = 'http://ros.org/wiki/' + text + refuri = 'http://wiki.ros.org/' + text node = nodes.reference(rawtext, text, refuri=refuri, **options) return [node], []