Merge branch 'cookbook-reorg' into 'develop'

Reorder cookbook sections and update style

See merge request orfeotoolbox/otb!415

Documentation/Cookbook/Scripts/otbGenerateWrappersRstDoc.py

@@ -404,7 +404,7 @@ def GenerateRstForApplications(rst_dir):
     appNames = [app for app in allApps if app not in blackList]
 
     appIndexFile = open(rst_dir + '/Applications.rst', 'w')
-    appIndexFile.write(RstPageHeading("Applications", "2", ref="apprefdoc"))
+    appIndexFile.write(RstPageHeading("All Applications", "2", ref="apprefdoc"))
 
     print("Generating rst for {} applications".format(len(appNames)))
 

Documentation/Cookbook/_static/css/otb_theme.css

-.wy-nav-content {
-    max-width: 800px;
+/* Style of the toctree captions
+ * inspired from sphinx-rtd-theme docs
+ */
+.wy-menu-vertical header, .wy-menu-vertical p.caption {
+    color: #2980b9; /* sphinx blue */
+    line-height: 32px;
+    font-weight: bold;
+    text-transform: uppercase;
+    white-space: nowrap;
+    margin-top: .8em;
 }
 
 /* Reduce the effect of the p bottom margin before lists
  * Very useful for choice parameters in app doc for example
  */
-p + ul {
+.wy-nav-content .document p + ul {
     margin-top: -18px;
 }
+
+/* Custom colors for the logo background */
+.wy-side-nav-search, .wy-nav-top {
+    background: #1e1f22; /* otb black */
+}
+
+.wy-side-nav-search input[type="text"] {
+    border-color: #1e1f22; /* otb black */
+}

Documentation/Cookbook/rst/OTB-Applications.rst → Documentation/Cookbook/rst/CliInterface.rst

-A brief tour of OTB Applications
-================================
+Command-line interface
+======================
 
 OTB ships with more than 100 ready to use applications for remote sensing tasks.
 They usually expose existing processing functions from the underlying C++
@@ -142,99 +142,6 @@ Parameters are passed to the application using the parameter key (which
 might include one or several ``.`` character), prefixed by a ``-``.
 Command-line examples are provided in the chapter :ref:`apprefdoc`.
 
-Graphical launcher
-------------------
-
-The graphical interface for the applications provides a useful
-interactive user interface to set the parameters, choose files, and
-monitor the execution progress.
-
-This launcher needs the same two arguments as the command line launcher:
-
-::
-
-    $ otbApplicationLauncherQt module_name [MODULEPATH]
-
-The application paths can be set with the ``OTB_APPLICATION_PATH``
-environment variable, as for the command line launcher. Also, as for the
-command-line application, a more simple script is generated and
-installed by OTB to ease the configuration of the module path: to
-launch the graphical user interface, one will start the
-``otbgui_Rescale`` script.
-
-The resulting graphical application displays a window with several tabs:
-
--  Parameters is where you set the parameters and execute the
-   application.
-
--  Logs is where you see the output given by the application during its
-   execution.
-
--  Progress is where you see a progress bar of the execution (not
-   available for all applications).
-
--  Documentation is where you find a summary of the application
-   documentation.
-
-In this interface, every optional parameter has a check box that you
-have to tick if you want to set a value and use this parameter. The
-mandatory parameters cannot be unchecked.
-
-The interface of the application is shown here as an example:
-
-.. figure:: Art/QtImages/rescale_param.png
-    :align: center
-
-Python interface
-----------------
-
-The applications can also be accessed from Python, through a module
-named ``otbApplication``. However, there are technical requirements to use it.
-If you use OTB through standalone packages, you should use the supplied
-environment script ``otbenv`` to properly setup variables such as
-``PYTHONPATH`` and ``OTB_APPLICATION_PATH`` (on Unix systems, don't forget to
-source the script). In other cases, you should set these variables depending on
-your configuration.
-
-On Unix systems, it is typically available in the ``/usr/lib/otb/python``
-directory. Depending on how you installed OTB, you may need to configure the
-environment variable ``PYTHONPATH`` to include this directory so that the module
-becomes available from Python.
-
-On Windows, you can install the ``otb-python`` package, and the module
-will be automatically available from an OSGeo4W shell.
-
-As for the command line and GUI launchers, the path to the application
-modules needs to be properly set with the ``OTB_APPLICATION_PATH``
-environment variable. The standard location on Unix systems is
-``/usr/lib/otb/applications``. On Windows, the applications are
-available in the ``otb-bin`` OSGeo4W package, and the environment is
-configured automatically so ``OTB_APPLICATION_PATH`` doesn't need to be modified
-``OTB_APPLICATION_PATH``.
-
-Once your environment is set, you can use OTB applications from Python, just
-like this small example:
-
-.. code-block:: python
-
-    #  Example on the use of the Smoothing application
-
-    # The python module providing access to OTB applications is otbApplication
-    import otbApplication as otb
-
-    # Let's create the application with codename "Smoothing"
-    app = otb.Registry.CreateApplication("Smoothing")
-
-    # We set its parameters
-    app.SetParameterString("in", "my_input_image.tif")
-    app.SetParameterString("type", "mean")
-    app.SetParameterString("out", "my_output_image.tif")
-
-    # This will execute the application and save the output file
-    app.ExecuteAndWriteOutput()
-
-For more information about this Python interface, check the recipe section.
-
 Load and save parameters to XML
 -------------------------------
 

Documentation/Cookbook/rst/CompilingOTBFromSource.rst

+.. _compilingfromsource:
+
 Compiling OTB from source
 =========================
 

Documentation/Cookbook/rst/EnvironmentVariables.rst

+Environment variables
+=====================
+
+The following environment variables are parsed by Orfeo ToolBox. Note
+that they only affect default values, and that settings in extended
+filenames, applications, Monteverdi or custom C++ code might override
+those values.
+
+* ``OTB_DEM_DIRECTORY``: Default directory were DEM tiles are
+  stored. It should only contain ```.hgt`` or or georeferenced
+  ``.tif`` files. Empty if not set (no directory set)
+* ``OTB_GEOID_FILE``: Default path to the geoid file that will be used
+  to retrieve height of DEM above ellipsoid. Empty if not set (no
+  geoid set)
+* ``OTB_MAX_RAM_HINT``: Default maximum memory that OTB should use for
+  processing, in MB. If not set, default value is 128 MB.
+* ``OTB_LOGGER_LEVEL``: Default level of logging for OTB. Should be
+  one of ``DEBUG``, ``INFO``, ``WARNING``, ``CRITICAL`` or ``FATAL``,
+  by increasing order of priority. Only messages with a higher
+  priority than the level of logging will be displayed. If not set,
+  default level is ``INFO``.
+
+In addition to OTB specific environment variables, the following
+environment variables are parsed by third party libraries and also
+affect how OTB works:
+
+* ``GDAL_CACHEMAX``: GDAL has an internal cache mechanism to avoid reading or decoding again image chunks. This environment variable controls the amount of memory that GDAL can use for caching. By default, GDAL can use up to 5 percent of the system's available RAM, which may be a lot. In addition, caching is only needed if the processing chain is likely to request the same chunk several times, which is unlikely to happen for a standard pixel based OTB pipeline. Setting a lower value facilitates the allocation of more memory to OTB itself (using applications ``-ram`` parameter or ``OTB_MAX_RAM_HINT`` environment variable). If the value is small, i.e. less than 100 000, it is assumed to be in megabytes, otherwise, it is assumed to be in bytes.
+* ``GDAL_NUM_THREADS``: GDAL can take advantage of multi-threading to decode some formats. This variable controls the number of threads GDAL is allowed to use.
+* ``OPJ_NUM_THREADS``: OpenJpeg can take advantage of multi-threading when decoding images. This variable controls the number of threads OpenJpeg is allowed to use.
+* ``ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS``: This variable controls the number of threads used by ITK for processing. 
+

Documentation/Cookbook/rst/AdvancedUse.rst → Documentation/Cookbook/rst/ExtendedFilenames.rst

-Advanced Use
-============
-
-This section describes advanced configuration options and tricks.
-
-Environment variables that affect Orfeo ToolBox
------------------------------------------------
-
-The following environment variables are parsed by Orfeo ToolBox. Note
-that they only affect default values, and that settings in extended
-filenames, applications, Monteverdi or custom C++ code might override
-those values.
-
-* ``OTB_DEM_DIRECTORY``: Default directory were DEM tiles are
-  stored. It should only contain ```.hgt`` or or georeferenced
-  ``.tif`` files. Empty if not set (no directory set)
-* ``OTB_GEOID_FILE``: Default path to the geoid file that will be used
-  to retrieve height of DEM above ellipsoid. Empty if not set (no
-  geoid set)
-* ``OTB_MAX_RAM_HINT``: Default maximum memory that OTB should use for
-  processing, in MB. If not set, default value is 128 MB.
-* ``OTB_LOGGER_LEVEL``: Default level of logging for OTB. Should be
-  one of ``DEBUG``, ``INFO``, ``WARNING``, ``CRITICAL`` or ``FATAL``,
-  by increasing order of priority. Only messages with a higher
-  priority than the level of logging will be displayed. If not set,
-  default level is ``INFO``.
-
-In addition to OTB specific environment variables, the following
-environment variables are parsed by third party libraries and also
-affect how OTB works:
-
-* ``GDAL_CACHEMAX``: GDAL has an internal cache mechanism to avoid reading or decoding again image chunks. This environment variable controls the amount of memory that GDAL can use for caching. By default, GDAL can use up to 5 percent of the system's available RAM, which may be a lot. In addition, caching is only needed if the processing chain is likely to request the same chunk several times, which is unlikely to happen for a standard pixel based OTB pipeline. Setting a lower value facilitates the allocation of more memory to OTB itself (using applications ``-ram`` parameter or ``OTB_MAX_RAM_HINT`` environment variable). If the value is small, i.e. less than 100 000, it is assumed to be in megabytes, otherwise, it is assumed to be in bytes.
-* ``GDAL_NUM_THREADS``: GDAL can take advantage of multi-threading to decode some formats. This variable controls the number of threads GDAL is allowed to use.
-* ``OPJ_NUM_THREADS``: OpenJpeg can take advantage of multi-threading when decoding images. This variable controls the number of threads OpenJpeg is allowed to use.
-* ``ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS``: This variable controls the number of threads used by ITK for processing. 
-  
 .. _extended-filenames:
 
 Extended filenames
-------------------
+==================
 
 Extended filenames are an interesting feature of OTB. With them, it is possible to control
 several aspects of the behavior of OTB in the OTB-Applications or in our

Documentation/Cookbook/rst/GraphicalInterface.rst

+Graphical interface
+===================
+
+The graphical interface for the applications provides a useful
+interactive user interface to set the parameters, choose files, and
+monitor the execution progress.
+
+This launcher needs the same two arguments as the command line launcher:
+
+::
+
+    $ otbApplicationLauncherQt module_name [MODULEPATH]
+
+The application paths can be set with the ``OTB_APPLICATION_PATH``
+environment variable, as for the command line launcher. Also, as for the
+command-line application, a more simple script is generated and
+installed by OTB to ease the configuration of the module path: to
+launch the graphical user interface, one will start the
+``otbgui_Rescale`` script.
+
+The resulting graphical application displays a window with several tabs:
+
+-  Parameters is where you set the parameters and execute the
+   application.
+
+-  Logs is where you see the output given by the application during its
+   execution.
+
+-  Progress is where you see a progress bar of the execution (not
+   available for all applications).
+
+-  Documentation is where you find a summary of the application
+   documentation.
+
+In this interface, every optional parameter has a check box that you
+have to tick if you want to set a value and use this parameter. The
+mandatory parameters cannot be unchecked.
+
+The interface of the application is shown here as an example:
+
+.. figure:: Art/QtImages/rescale_param.png
+    :align: center

Documentation/Cookbook/rst/Installation.rst

@@ -13,8 +13,7 @@ Other binaries can be available as packages (OSGeo packages,
 Debian/Ubuntu packages, OpenSuse packages), however be advised that they
 may not be up-to-date nor delivered with full features. If you want to
 build from source or if we don’t provide packages for your system,
-information is available in the `Software Guide <http://orfeo-toolbox.org/SoftwareGuide/>`_,
-in the section "Building from Source".
+information is available in the :ref:`compilingfromsource` section.
 
 You can get latest binary packages from our `Download page <https://www.orfeo-toolbox.org/download>`__.
 

Documentation/Cookbook/rst/recipes/python.rst → Documentation/Cookbook/rst/PythonAPI.rst

-OTB processing in Python
-========================
+Python API
+==========
+
+The applications can also be accessed from Python, through a module
+named ``otbApplication``. However, there are technical requirements to use it.
+If you use OTB through standalone packages, you should use the supplied
+environment script ``otbenv`` to properly setup variables such as
+``PYTHONPATH`` and ``OTB_APPLICATION_PATH`` (on Unix systems, don't forget to
+source the script). In other cases, you should set these variables depending on
+your configuration.
+
+On Unix systems, it is typically available in the ``/usr/lib/otb/python``
+directory. Depending on how you installed OTB, you may need to configure the
+environment variable ``PYTHONPATH`` to include this directory so that the module
+becomes available from Python.
+
+On Windows, you can install the ``otb-python`` package, and the module
+will be automatically available from an OSGeo4W shell.
+
+As for the command line and GUI launchers, the path to the application
+modules needs to be properly set with the ``OTB_APPLICATION_PATH``
+environment variable. The standard location on Unix systems is
+``/usr/lib/otb/applications``. On Windows, the applications are
+available in the ``otb-bin`` OSGeo4W package, and the environment is
+configured automatically so ``OTB_APPLICATION_PATH`` doesn't need to be modified
+``OTB_APPLICATION_PATH``.
+
+Once your environment is set, you can use OTB applications from Python, just
+like this small example:
+
+.. code-block:: python
+
+    #  Example on the use of the Smoothing application
+
+    # The python module providing access to OTB applications is otbApplication
+    import otbApplication as otb
+
+    # Let's create the application with codename "Smoothing"
+    app = otb.Registry.CreateApplication("Smoothing")
+
+    # We set its parameters
+    app.SetParameterString("in", "my_input_image.tif")
+    app.SetParameterString("type", "mean")
+    app.SetParameterString("out", "my_output_image.tif")
+
+    # This will execute the application and save the output file
+    app.ExecuteAndWriteOutput()
 
 Basics
 ------
@@ -374,4 +419,3 @@ that relate to geometry, projections, and also calibration.
 
 Future developments will probably offer a more adapted structure to import and
 export images between OTB and the Python world.
-

Documentation/Cookbook/rst/Recipes.rst

@@ -18,5 +18,3 @@ and demonstrate how they can be applied.
    recipes/pbclassif.rst
    recipes/featextract.rst
    recipes/stereo.rst
-   recipes/python.rst
-   

Documentation/Cookbook/rst/conf.py.in

@@ -53,10 +53,10 @@ source_suffix = '.rst'
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index_TOC'
+master_doc = 'index'
 
 # General information about the project.
-project = u'OTB CookBook'
+project = u'Orfeo ToolBox'
 copyright = u'@OTB_COPYRIGHT_TEXT@'
 #copyright = u'2014, OTB Team'
 # The version info for the project you're documenting, acts as replacement for
@@ -119,8 +119,9 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
-
+html_theme_options = {
+    'logo_only': True
+}
 
 
 # The name for this set of Sphinx documents.  If None, it defaults to
@@ -132,7 +133,7 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = "rst/Art/logo.png"
+html_logo = "rst/Art/logo-with-text.png"
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -222,7 +223,7 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  ('index_TOC', 'CookBook-@OTB_VERSION_MAJOR@.@OTB_VERSION_MINOR@.@OTB_VERSION_PATCH@.tex', u'OTB CookBook Documentation',
+  ('index', 'CookBook-@OTB_VERSION_MAJOR@.@OTB_VERSION_MINOR@.@OTB_VERSION_PATCH@.tex', u'OTB CookBook Documentation',
    u'OTB Team', 'manual'),
 ]
 

Documentation/Cookbook/rst/index.rst

-.. OTB documentation master file, created by
-   sphinx-quickstart on Thu Jul  9 11:22:08 2015
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to Orfeo ToolBox!
 =========================
 
@@ -44,3 +39,34 @@ For other documentation, be sure to read:
 - `Doxygen <http://orfeo-toolbox.org/doxygen/>`_, for exhaustive documentation
   of the C++ API.
 
+Table of Contents
+=================
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Get Started
+
+    Installation
+    Monteverdi
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Applications
+
+    CliInterface
+    GraphicalInterface
+    PythonAPI
+    QGISInterface
+    Recipes
+    Applications
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Advanced use
+
+    EnvironmentVariables
+    ExtendedFilenames
+    CompilingOTBFromSource
+    C++
+    FAQ
+    Contributors

Documentation/Cookbook/rst/index_TOC.rst

-Table of Contents
-=================
-
-.. toctree::
-   :maxdepth: 3
-
-   index
-   Installation
-   CompilingOTBFromSource
-   OTB-Applications
-   QGIS-interface
-   Monteverdi
-   AdvancedUse
-   Recipes
-   Applications
-   C++
-   FAQ
-   Contributors