fix a bunch of RST warnings, move the install and the quickquide from…

… object_recognition_doc
wg-perception · Feb 23, 2013 · 9cf2534 · 9cf2534
1 parent 02be39f
commit 9cf2534
Show file tree

Hide file tree

Showing 13 changed files with 229 additions and 176 deletions.
diff --git a/.gitignore b/.gitignore
@@ -14,3 +14,4 @@ bin
 *.yaml
 *.yml
 *~
+doc_config.py
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -64,17 +64,4 @@ catkin_doxygen(object_recognition_core-doxygen ${CMAKE_CURRENT_SOURCE_DIR}/inclu
 
 # Use the ecto scripts to build top-level documentation
 set(ecto_SPHINX_DIR ${CMAKE_CURRENT_SOURCE_DIR}/doc/source)
-ecto_sphinx(${CMAKE_CURRENT_SOURCE_DIR}/doc/source)
-
-# create a target to copy the doxygen files inside
-add_custom_target(object_recognition_doc-copy-doxygen-to-doc COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_BINARY_DIR}/object_ecognition_core/api ${CMAKE_BINARY_DIR}/doc/html/object_recognition_doc/api
-                                                             DEPENDS doxygen
-)
-
-# Make sure that doxygen is generated before sphinx docs
-add_dependencies(sphinx-doc object_recognition_doc-copy-doxygen-to-doc)
-
-# Add 'doc' target for convenience
-add_custom_target(doc DEPENDS sphinx-doc)
-
-
+ecto_sphinx(${CMAKE_CURRENT_SOURCE_DIR}/doc/source doc)
diff --git a/doc/doc_config.py.in b/doc/doc_config.py.in
@@ -11,11 +11,13 @@ breathe_projects = dict(object_recognition_core='${CMAKE_CURRENT_BINARY_DIR}/../
 # for release
 ork_module_url_root = 'http://wg-perception.github.com/'
 
-intersphinx_mapping = {'ork_capture': (ork_module_url_root + 'capture', None),
-                       'ork_linemod': (ork_module_url_root + 'linemod', None),
-                       'ork_tabletop': (ork_module_url_root + 'tabletop', None),
-                       'ork_tod': (ork_module_url_root + 'tod', None),
-                       'ork_transparent_object': (ork_module_url_root + 'transparent_objects', None),
+intersphinx_mapping = {'orkcapture': (ork_module_url_root + 'capture', None),
+                       'orklinemod': (ork_module_url_root + 'linemod', None),
+                       'orkreconstruction': (ork_module_url_root + 'reconstruction', None),
+                       'orkros': (ork_module_url_root + 'object_recognition_ros', None),
+                       'orktabletop': (ork_module_url_root + 'tabletop', None),
+                       'orktod': (ork_module_url_root + 'tod', None),
+                       'orktransparentobjects': (ork_module_url_root + 'transparent_objects', None),
                        }
 
 programoutput_path = '${DOC_SOURCE_DIRS}'.split(';')
diff --git a/doc/source/api/db.rst b/doc/source/api/db.rst
@@ -22,8 +22,4 @@ Implementing your own DB type
 -----------------------------
 
 If you want to create your own DB type, look at the examples from the core like CouchDb or filesystem.
-You have to inherit from:
-
-.. doxygenclass:: object_recognition_core::db::ObjectDbBase
-    :project: object_recognition_core
-    :members:
+You just have to inherit from ``ObjectDb``.
diff --git a/doc/source/api/detection.rst b/doc/source/api/detection.rst
@@ -8,7 +8,7 @@ Python Plasm
 
 Your pipeline has to provide an implementation of the :py:class:`object_recognition_core.pipelines.detection.DetectionPipeline` class to be fully integrated with object recognition infrastructure:
 
-.. autoclass:: object_recognition_core.pipelines.detection.DetectionPipeline
+.. autoclass:: object_recognition_core.pipelines.detection.DetectorBase
    :members:
 
 By providing so, after parsing the config file, the detection script will be able to find/load you cell when present on the PYTHONPATH.

diff --git a/doc/source/api/source_sink.rst b/doc/source/api/source_sink.rst
@@ -12,5 +12,5 @@ For a ``Source``:  :py:class:`object_recognition_core.io.source.SourceBase`:
 
 And for a ``Sink``: py:class:`object_recognition_core.io.source.SinkBase`:
 
-.. autoclass:: object_recognition_core.io.sink.Sink
+.. autoclass:: object_recognition_core.io.sink.SinkBase
    :members:
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -51,7 +51,7 @@
 todo_include_todos = True
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = []
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -152,7 +152,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

diff --git a/doc/source/install.rst b/doc/source/install.rst
@@ -21,66 +21,55 @@ Download & Build from Source
 
     If you want to install from source without ROS, you need to have common dependencies (OpenCV, PCL) on your path. You also need to execute the following:
 
-    .. code-block:: sh
-
-        sudo pip install rosinstall
-
-    Write a .rosinstall file containing:
 
-    the core:
+    .. code-block:: bash
 
-    .. literalinclude:: ../../install/rosinstall_main
-        :language: yaml
+        mkdir src && cd src
+        git clone http://github.com/ros/catkin.git
+        git clone http://github.com/ros-infrastructure/catkin_pkg.git
+        ln -s catkin/cmake/toplevel.cmake CMakeLists.txt
 
+    ``catkin`` is a set of CMake macros that simplify build and maintenance.
 
 .. toggle:: Fuerte
 
-    First source your ROS setup file:
+    First install catkin and source your ROS setup file:
 
     .. code-block:: sh
 
+        sudo apt-get install ros-fuerte-catkin ros-fuerte-ecto* ros-fuerte-opencv-candidate
         source /opt/ros/fuerte/setup.sh
 
-    Install rosinstall if you don't already have it:
+    Install the catkin package from source as the package does not have the toplevel.cmake file:
 
     .. code-block:: sh
 
-        sudo apt-get install python-rosinstall
-
-    Write a .rosinstall file containing:
-
-    the core:
+        git clone http://github.com/ros/catkin.git && git checkout fuerte-devel
+        ln -s catkin/toplevel.cmake CMakeLists.txt
 
-    .. literalinclude:: ../../install/rosinstall_main_fuerte
-        :language: yaml
 
 .. toggle:: Groovy
 
     First source your ROS setup file:
 
     .. code-block:: sh
 
+        sudo apt-get install ros-groovy-catkin ros-groovy-ecto* ros-groovy-opencv-candidate
         source /opt/ros/groovy/setup.sh
 
-    Install rosinstall if you don't already have it:
-
-    .. code-block:: sh
-
-        sudo apt-get install python-rosinstall
-
-    Write a .rosinstall file containing:
+Then install any pipeline you need:
 
-    the core:
-
-    .. literalinclude:: ../../install/rosinstall_main
-        :language: yaml
-
-the pipelines:
+.. code-block:: sh
 
-.. literalinclude:: ../../install/rosinstall_pipelines
-    :language: yaml
+    git clone http://github.com/wg-perception/object_recognition_core
+    git clone http://github.com/wg-perception/capture
+    git clone http://github.com/wg-perception/reconstruction
+    git clone http://github.com/wg-perception/linemod
+    git clone http://github.com/wg-perception/tabletop
+    git clone http://github.com/wg-perception/tod
+    git clone http://github.com/wg-perception/transparent_objects
 
-ROS stuff:
+any ROS stuff:
 
 .. toggle_table::
     :arg1: Non-ROS
@@ -94,74 +83,55 @@ ROS stuff:
 
 .. toggle:: Fuerte
 
-    .. literalinclude:: ../../install/rosinstall_ros_fuerte
-        :language: yaml
+    .. code-block:: sh
 
+        git clone http://github.com/wg-perception/object_recognition_msgs
+        git clone http://github.com/wg-perception/object_recognition_ros
 
 .. toggle:: Groovy
 
-    .. literalinclude:: ../../install/rosinstall_ros
-       :language: yaml
-
-
-You'll notice that one of the packages is ``catkin`` http://www.ros.org/wiki/catkin. It is a set of CMake macros that simplify build and maintenance.
-If you are a developer and have write access to the repositories, search and replace ``https://`` above and replace by ``git@github.com:``.
-
-Then simply run:
+    .. code-block:: sh
 
-.. code-block:: sh
+        git clone http://github.com/wg-perception/object_recognition_msgs
+        git clone http://github.com/wg-perception/object_recognition_ros 
 
-    rosinstall . .rosinstall
 
+and then build your code:
 
-Set the main ``CMakeLists.txt`` file:
 
 .. toggle_table::
     :arg1: Non-ROS
     :arg2: Fuerte
     :arg3: Groovy
 
+
 .. toggle:: Non-ROS
 
     .. code-block:: sh
 
-        ln -s catkin/cmake/toplevel.cmake CMakeLists.txt
-
+        cd ../ && mkdir build && cd build && cmake ../src && make
 
 
 .. toggle:: Fuerte
 
     .. code-block:: sh
 
-        ln -s catkin/toplevel.cmake CMakeLists.txt
-
+        mkdir ../cd ../ && mkdir build && cd build && cmake ../src && make
 
 
 .. toggle:: Groovy
 
     .. code-block:: sh
 
-        ln -s catkin/cmake/toplevel.cmake CMakeLists.txt
-
-
-The different components should then be copied over.
+        cd ../ && catkin_make
 
-From here on, it's a normal CMake build:
 
-.. code-block:: sh
 
-    mkdir build
-    cd build
-    cmake ..
-    make
+If you are a developer and have write access to the repositories, search and replace ``https://`` above and replace by ``git@github.com:``.
 
-To maintain your code, each folder is each own ``git`` repository and you can pull/push from there. Little convenience: if you want to update everything:
 
-.. code-block:: sh
+To maintain your code, each folder is each own ``git`` repository and you can pull/push from there.
 
-    source build/buildspace/setup.sh
-    catkin_ws pull
-    
 Building the documentation
 --------------------------
 
@@ -174,16 +144,6 @@ You will need some up to date packages:
 
   sudo pip install -U breathe sphinxcontrib-programoutput
 
-And you will need to add the object_recognition_doc package to your workspace:
-
-  https://github.com/wg-perception/object_recognition_doc
-
-or add to your rosinstall:
-
-.. code-block:: yaml
-
-  - git: {local-name: object_recognition_doc, uri: 'https://github.com/wg-perception/object_recognition_doc.git'}
-
 From the root, just type:
 ::
 
@@ -193,22 +153,4 @@ From the root, just type:
   
 You will find the generated documentation under ``build/doc/html``.
 
-If you want to upload the documentation to the webserver, it's a bit harder because of intersphinx (you will alsoneed developer access to do that).
-
-First, build the docs making sure that ``ecto_module_root`` is set to the source version in ``ecto/doc/kitchen/doc_config.py``. Then rsync
-::
-
-
-  rsync -vrz --delete build/doc/html/ecto/ ecto.willowgarage.com:/var/www/
-  rsync -vrz --delete build/doc/html/object_recognition_doc/ ecto.willowgarage.com:/var/www/recognition
-  rsync -vrz --delete build/doc/html/ecto_* ecto.willowgarage.com:/var/www/
-
-Then, build the docs again setting ``ecto_module_root`` to the release version. Then rsync again
-::
-
-  rsync -vrz --delete build/doc/html/ecto/ ecto.willowgarage.com:/var/www/
-  rsync -vrz --delete build/doc/html/object_recognition_doc/ ecto.willowgarage.com:/var/www/recognition
-  rsync -vrz --delete build/doc/html/ecto_* ecto.willowgarage.com:/var/www/
-
-
-
+Once the documentation is built, you can simply copy it (except for the ``.doctree`` folder) to the ``gh-pages`` branch on GitHub.