rst format fixes

doc/source/ClangFormat.rst

@@ -88,10 +88,10 @@ ClangFormat configuration while concurrently modifying/adding code.
 The plugin of your choice should:
 
 - Format code based on the `.clang-format` file placed in the MRPT root
-    directory.
-- Use the ClangFormat version especified at the top of this page. This is 
-because part of the configuration directives are not compatible with 
-previous ClangFormat versions.
+  directory.
+- Use the ClangFormat version especified at the top of this page. This is
+  because part of the configuration directives are not compatible with
+  previous ClangFormat versions.
 
 Refer to the docs of the corresponding plugin for tweaking its behavior.
 Also, do check the `MRPT Coding style <https://github.com/MRPT/mrpt/blob/master/doc/MRPT_Coding_Style.md>`_
@@ -103,4 +103,3 @@ Past discussion links
 - `Discussion issue <https://github.com/MRPT/mrpt/issues/520>`_
 - `Pull-Request <https://github.com/MRPT/mrpt/pull/556>`_
 - `Pull-Request #2 <https://github.com/MRPT/mrpt/pull/559>`_
-

doc/source/ClangFormat_internal.rst

@@ -6,7 +6,7 @@ This file primarily outlines the procedure of formatting the entire MRPT
 codebase with ClangFormat in case this is needed again, or in case we upgrade to
 a more recent version of ClangFormat.
 
-Notes on formatting the codebase 
+Notes on formatting the codebase
 --------------------------------------------------------
 
 At present (Dec-2019) we use ``clang-format-8``.
@@ -23,6 +23,6 @@ keeps reindenting comments between successive ClangFormat runs.
 Porting to a new ClangFormat version
 ----------------------------------------
 
-- Change the version specified in
-    `clang_git_format/config.py <https://github.com/MRPT/mrpt/blob/master/scripts/clang_git_format/clang_git_format/config.py>`_.
+- Change the version specified in `clang_git_format/config.py <https://github.com/MRPT/mrpt/blob/master/scripts/clang_git_format/clang_git_format/config.py>`_.
+
 - Rerun the `clang_format_codebase.sh script <https://github.com/MRPT/mrpt/blob/master/scripts/clang_format_codebase.sh>`_.

doc/source/MRPT_Coding_Style.rst

@@ -2,30 +2,32 @@
 C++ coding style for MRPT
 ===========================
 
+.. contents:: :local:
+
 General rules
 ------------------
 
-* Take a look at `Google's C++ style guide <https://google.github.io/styleguide/cppguide.html>`m_
-for very good general advices and reasons to worry about code style. It is worth reading carefully.
+* Take a look at `Google's C++ style guide <https://google.github.io/styleguide/cppguide.html>`_
+  for very good general advises and reasons to worry about code style. It is worth reading carefully.
 
 * Since mrpt 2.0 we use C++17.
 
 Class and filenames
 ----------------------
 
 * For historical reasons, most MRPT classes and structures use the prefix `C`
-    and `T`, respectively. For example: `class CBar`and `struct TFoo`. This
-    convention *should* be observed in new code for the sake of consistency.
+  and `T`, respectively. For example: `class CBar`and `struct TFoo`. This
+  convention *should* be observed in new code for the sake of consistency.
 * A class named `CFoo` should have its declaration in a file named `CFoo.h` and
-    its implementation in `CFoo.cpp`. Pure template classes may have detailed
-    implementations in `CFoo_impl.h`.
+  its implementation in `CFoo.cpp`. Pure template classes may have detailed
+  implementations in `CFoo_impl.h`.
 * Each MRPT library, or "module", has its own directory under `MRPT/libs`, with
-    its own `include` and `src` directory. More on source tree layout
-    `here <http://www.mrpt.org/libs_tree_layout>`_.
+  its own `include` and `src` directory. More on source tree layout
+  `here <http://www.mrpt.org/libs_tree_layout>`_.
 * Use the #include guard `#pragma once <https://en.wikipedia.org/wiki/Pragma_once>`_ in new code.
 
 Code content and style
-------------------------
+-----------------------
 
 Tabs vs Spaces
 =================
@@ -38,15 +40,19 @@ More specifically:
 
 * Enable *viewing of whitespaces* in your editor of choice, e.g.,:
 
-    * Visual Studio: `ctrl+shift+8`
-    * Vim:
-        ```vim
-        set listchars=eol:¬,tab:>·,trail:~,extends:>,precedes:<
-        set list
-        ```
-* Change the default editor settings so that you
-    * Use 1 tab for indentation
-        * Use an additional tab for *hanging indentation* (e.g. for open parenthesis
+  * Visual Studio: `ctrl+shift+8`
+  * Vim:
+
+  .. code-block:: vim
+
+    set listchars=eol:¬,tab:>·,trail:~,extends:>,precedes:<
+    set list
+
+* Change the default editor settings so that you:
+
+  * Use 1 tab for indentation
+
+    * Use an additional tab for *hanging indentation* (e.g. for open parenthesis
         cases)
     * Use spaces for splitting words in the same line, aligning code snippets
         etc.
@@ -64,13 +70,13 @@ there, a space is assumed.
 
 **Wrong inline alignment**
 
-.. image:: images/wrong_inline_alignment.png
+.. image:: images/vim_wrong_inline_alignment.png
 
 **Correct inline alignment**
 
-.. image:: images/correct_inline_alignment.png
+.. image:: images/vim_correct_inline_indentation.png
 
-Finally, if you are a vim-user you can add `this snippet of code <https://gist.github.com/bergercookie/9a2e96e19733b32ca55b8e2940eaba2c>`_ 
+Finally, if you are a vim-user you can add `this snippet of code <https://gist.github.com/bergercookie/9a2e96e19733b32ca55b8e2940eaba2c>`_
 to your `.vimrc` to enable the aforementioned settings.
 
 Misc
@@ -83,30 +89,30 @@ Misc
 
 * Member variables of a `struct` should have **no** suffix or prefix, e.g:
 
-  ```c++
-  struct TFoo {
-    int num_iters;
-  };
-  ```
+  .. code-block:: cpp
+
+    struct TFoo {
+      int num_iters;
+    };
 
 * Public variable of a `class` should have **no** suffic or prefix.
     Private/protected members should have the `m_` prefix or, alternatively, the
     `_` suffix. For *methods*, use **lower camel case** or K&R style, e.g.
 
-  ```c++
-  class CBar {
-  public:
-    int num_iters;
-    void doSomething(); // Lower camel case (preferred)
-    void do_something(); // K&R style (second style option)
-  private:
-    int m_handle;
-  };
-  ```
+    .. code-block:: cpp
+
+      class CBar {
+      public:
+        int num_iters;
+        void doSomething(); // Lower camel case (preferred)
+        void do_something(); // K&R style (second style option)
+      private:
+        int m_handle;
+      };
 
 * In general, `typedefs` and `using` will use lowercase with underscores, e.g.
    `using vector_int = std::vector<int>;`
 
 * If a packed structure is defined (i.e. `#pragma pack(push,1) ... #pragma pack(pop)`),
-it will be much safer to make all fields protected and offer accessor methods.
-In this way, we avoid alignment errors in some processor architectures.
+  it will be much safer to make all fields protected and offer accessor methods.
+  In this way, we avoid alignment errors in some processor architectures.

doc/source/compiling.rst

@@ -4,12 +4,75 @@
 Compiling
 #########
 
+This page describes how to build MRPT from sources. If you want instead to
+install the binaries and getting quickly into developing your MRPT-based
+applications, go to the `download page <download-mrpt.html>`_ and grab the
+binaries for your system or install via ``apt`` in Ubuntu.
 
-Dependencies
+.. contents:: :local:
+
+
+1. Dependencies
 --------------
 
 Check out `this page <dependencies.html>`_ to find out what are needed for each
 of the MRPT build dependencies (opencv, wxWidgets,...) to decide if you need
 them for your applications.
 
-Get the latest source code version with: ``git clone https://github.com/MRPT/mrpt.git``
+
+
+2. Build using cmake
+-------------------
+
+Using the console
+~~~~~~~~~~~~~~~~~~~
+
+The usual cmake stuff:
+
+.. code-block:: bash
+
+  cd mrpt
+  mkdir build
+  cd build
+  cmake ..
+  cmake --build .
+
+Using cmake-gui
+~~~~~~~~~~~~~~~~~~~
+
+- Open cmake-gui (Available for Windows/Linux) and set the “source dir” to the
+  root directory of the MRPT source package you have downloaded.
+- Set the “binary directory” to a new, empty directory where to generate the
+  project files.
+- Press “configure”, check for errors, tune the options as required (read below for a description of some options) and finally click “Generate”.
+- Click on "open project" and build as usual.
+
+3. CMake build options
+---------------------
+For all platforms/compilers:
+
+- ``BUILD_APPLICATIONS`` : By default ON, if unchecked the applications won’t be built. Useful if you only want to build MRPT libraries. Notice that you can also always use the MRPT_BUILD_DIR/libs/MRPT_ALL_LIB.* solution (or Makefile) to achieve the same.
+- ``BUILD_xSENS``: Whether to use the CMT library for interfacing xSens inertial sensors. Default is ON.
+- ``BUILD_EXAMPLES``: Whether you want to compile all the examples in the “/samples” directory. Default is OFF.
+- ``BUILD_KINECT``: By default ON. Uncheck if you don’t have the required dependencies (read above for your OS).
+- ``BUILD_SHARED_LIBS``: Build static libraries if set to OFF, or dynamic libraries (.so/.dll) otherwise. Default is ON, and it’s strongly recommended to always use shared libs unless you have special need for static ones.
+- ``EIGEN_USE_EMBEDDED_VERSION``: By default O, instructs MRPT to use the Eigen headers in MRPT/otherlibs/eigen3/. Uncheck if you have Eigen installed in the system and it’s visible through pkg-config. It’s recommended to uncheck this option if you have eigen3 installed in your system (today, eigen3 it’s not yet in any distro repository, that’s why it’s ON by default).
+- ``MRPT_ALWAYS_CHECKS_DEBUG``: If set to ON, additional security checks will be performed at run-time in many classes. Default is OFF.
+- ``MRPT_ALWAYS_CHECKS_DEBUG_MATRICES``: If set to ON, additional security checks will be performed at run-time in several Matrix operations. Default is ON.
+- ``MRPT_ENABLE_EMBEDDED_ENABLED_PROFILER``: If enabled, all code blocks within macros "MRPT_BEGIN/MRPT_END" will be profiled and the statistics dumped to the console at the end of execution of any program. Default is OFF.
+- ``MRPT_HAS_ASIAN_FONTS``: Enables Asian fonts in mrpt::img::CCanvas (see this page), but increases library size by 1.5Mb. Default is ON.
+- ``MRPT_HAS_SVS``: To enable integration of the Videre SVS libraries to interface their stereo cameras. You’ll need the vendor libraries installed in the system before to enable this option. After setting this option to “ON”, the new configuration fields “SVS_ROOT_DIR” will appear and will be tried to be set pointing to the directory where the library is (As of Aug/2010, this option only works in GNU/Linux).
+- ``MRPT_OCCUPANCY_GRID_CELLSIZE``: Can be either 8 or 16 (bits). The size of each cell in the class mrpt::slam::COccupancyGridMap2D. Default is 8 bits. More on this here.
+
+For Windows only:
+
+- ``MRPT_HAS_FFMPEG_WIN32``: Enable this and (after running “Configure”) then
+  set FFMPEG_WIN32_ROOT_DIR to the directory where FFmpeg binaries have been
+  uncompressed (e.g. “c:\ffmpeg-r16537-gpl-lshared-win32”).
+- ``MRPT_HAS_BUMBLEBEE``: To enable integration of the Bumblebee stereo camera SDK. You’ll need the vendor provided “Triclops” and “Digiclops” libraries. After setting this option to “ON”, the new configuration fields “BUMBLEBEE_DIGICLOPS_ROOT_DIR” and “BUMBLEBEE_TRICLOPS_ROOT_DIR” will appear where the correct corresponding paths must be entered.
+
+For GNU GCC compiler only:
+
+- ``MRPT_ENABLE_LIBSTD_PARALLEL_MODE``: Enables the GNU libstdc++ parallel mode (See http://gcc.gnu.org/onlinedocs/libstdc++/manual/parallel_mode.html. Default is OFF.
+- ``MRPT_ENABLE_PROFILING``: Enables generation of information required for profiling. Default is OFF.
+- ``MRPT_OPTIMIZE_NATIVE``: Enables optimization for the current architecture (-mtune=native). Default is OFF for old GCC versions, ON for 4.2+. If you have an old version of GCC (<4.2), this option cannot be set since it’s not recognized by the compiler. Instead, set USER_EXTRA_CPP_FLAGS to the optimization flags for your platform, for example: -march=pentium4.

doc/source/download-mrpt.rst

@@ -0,0 +1,37 @@
+.. _downloadmrpt:
+
+##############
+Download MRPT
+##############
+
+.. contents:: :local:
+
+
+Source code
+-------------
+
+xxx
+
+Next step: :ref:`compiling`
+
+Debian/Ubuntu official repositories
+---------------------------------------
+
+xxx
+
+
+Debian/Ubuntu PPA: last stable release
+---------------------------------------
+
+xxx
+
+
+Debian/Ubuntu PPA: nightly builds
+---------------------------------------
+
+xxx
+
+Windows installer
+--------------------
+
+xxx

doc/source/index.rst

@@ -5,9 +5,10 @@ MRPT
 .. toctree::
   :maxdepth: 2
   :hidden:
-  
+
   install
   compiling
+  download-mrpt
   modules
   tutorials
   contributing
@@ -27,10 +28,10 @@ employed in common robotics research areas.
 It is open source, released under the `BSD license <license.html>`_.
 
 
-Set it up
-------------
+Get it
+--------
 
-- :ref:`install`: for installing binaries for Linux or Windows.
+- :ref:`downloadmrpt`: for installing for Linux or Windows.
 - :ref:`compiling`: to build from sources.
 
 Where to start
@@ -42,7 +43,7 @@ Where to start
 - Ask questions at the mail list `[email protected] <https://groups.google.com/forum/#!forum/mrpt-users>`_ or at `stackoverflow <https://stackoverflow.com/search?q=mrpt>`_  using the tag `mrpt`.
 - ROS packages: `mrpt_navigation <https://wiki.ros.org/mrpt_navigation>`_, `mrpt_slam <https://wiki.ros.org/mrpt_slam>`_.
 - `Bindings documentation <https://github.com/MRPT/mrpt/wiki>`_ (Python, Matlab)
-- Example configuration files for  MRPT applications can be found at: 
+- Example configuration files for  MRPT applications can be found at:
   `MRPT/share/mrpt/config_files <https://github.com/MRPT/mrpt/tree/master/share/mrpt/config_files>`_.
 - Some sample datasets are stored in:
   `MRPT/share/mrpt/datasets <https://github.com/MRPT/mrpt/tree/master/share/mrpt/datasets>`_.

doc/source/range_only_localization_mapping.rst

@@ -4,6 +4,8 @@
 Range-only Localization and Mapping Solutions
 =================================================
 
+.. contents:: :local:
+
 Range-only SLAM
 ====================
 
@@ -16,7 +18,7 @@ requires a decent odometry as input, which can comprise 2D or 3D robot motion
 actions.
 
 Range-only Localization
-====================
+==========================
 
 There are two implementations: