From 6695b0406bce44ffc34808b16cfd360590e7edcf Mon Sep 17 00:00:00 2001 From: Damon Kohler Date: Thu, 25 Aug 2016 15:16:33 +0200 Subject: [PATCH] Moves the bulk of our documentation into Sphinx. (#28) --- README.md | 60 ----------------------------- README.rst | 55 +++++++++++++++++++++++++++ docs/source/index.rst | 87 ++++++++++++++++++++++++++++++++++++++----- 3 files changed, 133 insertions(+), 69 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/README.md b/README.md deleted file mode 100644 index 5cb9f18..0000000 --- a/README.md +++ /dev/null @@ -1,60 +0,0 @@ -# Cartographer Project Overview - -See https://github.com/googlecartographer/cartographer - -## Installation - -Installation has been tested on Ubuntu 14.04 (Trusty) with ROS Indigo and on Ubuntu 16.04 (Xenial) with ROS Kinetic. For ROS Kinetic, simply replace the two occurrences of "indigo" with "kinetic" in the instructions below. There are multiple options for building cartographer_ros as part of a ROS workspace. Two common use cases are described below. - -These dependencies always have to be installed: - - # Install the required libraries that are available as debs - sudo apt-get install \ - ros-indigo-tf2-eigen \ - g++ \ - google-mock \ - libboost-all-dev \ - liblua5.2-dev \ - libprotobuf-dev \ - libsuitesparse-dev \ - libwebp-dev \ - protobuf-compiler \ - python-sphinx \ - libpcap-dev # For 3D SLAM with Velodynes - - -### Standalone Workspace - - # Set up your Catkin workspace - mkdir -p ~/catkin_ws/src - cd ~/catkin_ws/src - source /opt/ros/indigo/setup.bash - catkin_init_workspace - - # Clone the necessary repos into your Catkin workspace - git clone https://github.com/googlecartographer/cartographer.git - git clone https://github.com/googlecartographer/cartographer_ros.git - git clone https://github.com/ethz-asl/ceres_catkin.git # Caution! Make sure you do not have "suitesparse" in your Catkin workspace - git clone https://github.com/ethz-asl/glog_catkin.git - git clone https://github.com/ethz-asl/gflags_catkin.git - git clone https://github.com/ethz-asl/catkin_simple.git - git clone https://github.com/ros-drivers/velodyne.git # For 3D SLAM with Velodynes - - # Build everything in your Catkin workspace - cd ~/catkin_ws - catkin_make_isolated - source devel_isolated/setup.bash - -### Using wstool - -If cartographer_ros is to be used as part of a pre-existing workspace/existing project, using [wstool](http://wiki.ros.org/wstool) is recommended. - - # Enter workspace root (i.e. the folder that has "src" as a subfolder) - # Merge the cartographer_ros rosinstall file - wstool merge https://raw.githubusercontent.com/googlecartographer/cartographer_ros/master/cartographer_ros.rosinstall - - # Update workspace - wstool update - - # Build workspace contents. It is recommended to use catkin tools: - catkin build diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..5981907 --- /dev/null +++ b/README.rst @@ -0,0 +1,55 @@ +.. Copyright 2016 The Cartographer Authors + +.. 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. + +.. Cartographer documentation master file, created by + sphinx-quickstart on Fri Jul 8 10:41:33 2016. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +============================ +Cartographer ROS Integration +============================ + +|docs| + +Purpose +======= + +`Cartographer`_ is a system that provides real-time simultaneous localization +and mapping `SLAM`_ across multiple platforms and sensor configurations. This +project provides Cartographer's ROS integration. + +.. _Cartographer: http://www.github.com/googlecartographer/cartographer +.. _SLAM: http://en.wikipedia.org/wiki/Simultaneous_localization_and_mapping + +Documentation +============= + +You will find complete documentation for using Cartographer with ROS at `our +Read the Docs site`_. + +.. _our Read the Docs site: https://google-cartographer-ros.readthedocs.io + +Contributing +============ + +You can find information about contributing to Cartographer's ROS integration +at our `Contribution page`_. + +.. _Contribution page: https://github.com/googlecartographer/cartographer_ros/blob/master/CONTRIBUTING.md + +.. |docs| image:: https://readthedocs.org/projects/google-cartographer-ros/badge/?version=latest + :alt: Documentation Status + :scale: 100% + :target: https://google-cartographer-ros.readthedocs.io/en/latest/?badge=latest diff --git a/docs/source/index.rst b/docs/source/index.rst index f6610b7..a50b4ae 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -17,19 +17,88 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to Cartographer's documentation! -======================================== - -Contents: +============================ +Cartographer ROS Integration +============================ .. toctree:: :maxdepth: 2 + :hidden: +`Cartographer`_ is a system that provides real-time simultaneous localization +and mapping `SLAM`_ across multiple platforms and sensor configurations. This +project provides Cartographer's ROS integration. +.. _Cartographer: https://github.com/googlecartographer/cartographer +.. _SLAM: http://en.wikipedia.org/wiki/Simultaneous_localization_and_mapping -Indices and tables -================== +Getting Started +=============== -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +Installation has been tested on Ubuntu 14.04 (Trusty) with ROS Indigo and on +Ubuntu 16.04 (Xenial) with ROS Kinetic. For ROS Kinetic, simply replace the two +occurrences of "indigo" with "kinetic" in the instructions below. There are +multiple options for building cartographer_ros as part of a ROS workspace. Two +common use cases are described below. + +These dependencies always have to be installed: + + .. code-block:: bash + + # Install the required libraries that are available as debs + sudo apt-get install \ + ros-indigo-tf2-eigen \ + g++ \ + google-mock \ + libboost-all-dev \ + liblua5.2-dev \ + libprotobuf-dev \ + libsuitesparse-dev \ + libwebp-dev \ + protobuf-compiler \ + python-sphinx \ + libpcap-dev # For 3D SLAM with Velodynes + +Standalone Workspace +-------------------- + + .. code-block:: bash + + # Set up your Catkin workspace + mkdir -p ~/catkin_ws/src + cd ~/catkin_ws/src + source /opt/ros/indigo/setup.bash + catkin_init_workspace + + # Clone the necessary repos into your Catkin workspace + git clone https://github.com/googlecartographer/cartographer.git + git clone https://github.com/googlecartographer/cartographer_ros.git + git clone https://github.com/ethz-asl/ceres_catkin.git # Caution! Make sure you do not have "suitesparse" in your Catkin workspace + git clone https://github.com/ethz-asl/glog_catkin.git + git clone https://github.com/ethz-asl/gflags_catkin.git + git clone https://github.com/ethz-asl/catkin_simple.git + git clone https://github.com/ros-drivers/velodyne.git # For 3D SLAM with Velodynes + + # Build everything in your Catkin workspace + cd ~/catkin_ws + catkin_make_isolated + source devel_isolated/setup.bash + +Using ``wstool`` +---------------- + +If ``cartographer_ros`` is to be used as part of a pre-existing +workspace/existing project, using `wstool ` is +recommended. + + .. code-block:: bash + + # Enter workspace root (i.e. the folder that has "src" as a subfolder) + # Merge the cartographer_ros rosinstall file + wstool merge https://raw.githubusercontent.com/googlecartographer/cartographer_ros/master/cartographer_ros.rosinstall + + # Update workspace + wstool update + + # Build workspace contents. It is recommended to use catkin tools: + catkin build