formatting rst

tdegeus · Dec 8, 2023 · 1913372 · 1913372
1 parent 11ac6ae
commit 1913372
Show file tree

Hide file tree

Showing 4 changed files with 113 additions and 82 deletions.
diff --git a/docs/cpp_install.rst b/docs/cpp_install.rst
@@ -1,77 +1,93 @@
-Compiling
-=========
+###########
+ Compiling
+###########
 
-Getting GooseEYE
-----------------
+******************
+ Getting GooseEYE
+******************
 
 Using conda
-^^^^^^^^^^^
+===========
 
-The easiest is to use *conda* to install *GooseEYE*::
+The easiest is to use *conda* to install *GooseEYE*:
 
-    conda install -c conda-forge gooseeye
+.. code::
+
+   conda install -c conda-forge gooseeye
 
 From source
-^^^^^^^^^^^
+===========
+
+Download the package:
+
+.. code::
 
-Download the package::
+   git checkout https://github.com/tdegeus/GooseEYE.git
+   cd GooseEYE
 
-    git checkout https://github.com/tdegeus/GooseEYE.git
-    cd GooseEYE
+Install headers, *CMake* and *pkg-config* support:
 
-Install headers, *CMake* and *pkg-config* support::
+.. code::
 
-    cmake .
-    make install
+   cmake .
+   make install
 
-Compiling
----------
+***********
+ Compiling
+***********
 
 Using CMake
-^^^^^^^^^^^
+===========
 
-The following structure can be used for your project's ``CMakeLists.txt``:
+The following structure can be used for your project's
+``CMakeLists.txt``:
 
-.. code-block:: cmake
+.. code:: cmake
 
-    find_package(GooseEYE REQUIRED)
+   find_package(GooseEYE REQUIRED)
 
-    add_executable(myexec mymain.cpp)
+   add_executable(myexec mymain.cpp)
 
-    target_link_libraries(myexec PRIVATE
-        GooseEYE
-        xtensor::optimize
-        xtensor::use_xsimd)
+   target_link_libraries(myexec PRIVATE
+       GooseEYE
+       xtensor::optimize
+       xtensor::use_xsimd)
 
-See the `documentation of xtensor <https://xtensor.readthedocs.io/en/latest/>`_
-concerning optimisation.
+See the `documentation of xtensor
+<https://xtensor.readthedocs.io/en/latest/>`_ concerning optimisation.
 
 .. note::
 
-    There are additional targets available to expedite your ``CMakeLists.txt``:
+   There are additional targets available to expedite your
+   ``CMakeLists.txt``:
 
-    *   ``GooseEYE::assert``:
-        enable GooseEYE assertions by defining ``GOOSEEYE_ENABLE_ASSERT``.
+   -  ``GooseEYE::assert``: enable GooseEYE assertions by defining
+      ``GOOSEEYE_ENABLE_ASSERT``.
 
-    *   ``GooseEYE::debug``:
-        enable GooseEYE assertions by defining ``GOOSEEYE_ENABLE_ASSERT`` and
-        xtensor assertions by defining ``XTENSOR_ENABLE_ASSERT`` (slow).
+   -  ``GooseEYE::debug``: enable GooseEYE assertions by defining
+      ``GOOSEEYE_ENABLE_ASSERT`` and xtensor assertions by defining
+      ``XTENSOR_ENABLE_ASSERT`` (slow).
 
-    *   ``GooseEYE::compiler_warnings``:
-        enable compiler warnings (generic).
+   -  ``GooseEYE::compiler_warnings``: enable compiler warnings
+      (generic).
 
 By hand
-^^^^^^^
+=======
 
-Presuming that the compiler is ``c++``, compile using::
+Presuming that the compiler is ``c++``, compile using:
 
-    c++ -I/path/to/GooseEYE/include ...
+.. code::
 
-Note that you have to take care of the *xtensor* dependency, the C++ version, optimisation, enabling *xsimd*, ...
+   c++ -I/path/to/GooseEYE/include ...
+
+Note that you have to take care of the *xtensor* dependency, the C++
+version, optimisation, enabling *xsimd*, ...
 
 Using pkg-config
-^^^^^^^^^^^^^^^^
+================
+
+Find the location of the headers can be automatised using *pkg-config*:
 
-Find the location of the headers can be automatised using *pkg-config*::
+.. code::
 
-    pkg-config --cflags GooseEYE
+   pkg-config --cflags GooseEYE
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,9 +1,12 @@
+##########
+ GooseEYE
+##########
 
-********
-GooseEYE
-********
-
-GooseEYE can be used from C++ or as a Python module. Please consider the theory and examples below that describe briefly the different measurements and their interpretation, accompanied by a C++ and a Python example. Since this is a research code, the code itself is the best reference.
+GooseEYE can be used from C++ or as a Python module. Please consider the
+theory and examples below that describe briefly the different
+measurements and their interpretation, accompanied by a C++ and a Python
+example. Since this is a research code, the code itself is the best
+reference.
 
 .. toctree::
    :caption: THEORY & EXAMPLES
@@ -37,9 +40,10 @@ GooseEYE can be used from C++ or as a Python module. Please consider the theory
    python_install.rst
    python_usage.rst
 
-Indices and tables
-==================
+********************
+ Indices and tables
+********************
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+-  :ref:`genindex`
+-  :ref:`modindex`
+-  :ref:`search`
diff --git a/docs/python_usage.rst b/docs/python_usage.rst
@@ -1,22 +1,22 @@
-*****************
-Functions & Usage
-*****************
+###################
+ Functions & Usage
+###################
 
-The Python interface is a simple wrapper around the C++ classes and functions. In general the Python and C++ codes are almost identical, with as only differences:
-
-*   The C++ ``xt::xarray`` are ``numpy.ndarray`` in Python.
-
-*   The syntax ``::`` in Python in simply a ``.``.
+The Python interface is a simple wrapper around the C++ classes and
+functions. In general the Python and C++ codes are almost identical,
+with as only differences:
 
+-  The C++ ``xt::xarray`` are ``numpy.ndarray`` in Python.
+-  The syntax ``::`` in Python in simply a ``.``.
 
 For example:
 
-.. code-block:: cpp
+.. code:: cpp
 
-    GooseEYE::Ensemble ensemble({51, 51});
+   GooseEYE::Ensemble ensemble({51, 51});
 
 In Python is
 
-.. code-block:: python
+.. code:: python
 
-    ensemble = GooseEYE.Ensemble([51, 51])
+   ensemble = GooseEYE.Ensemble([51, 51])
diff --git a/docs/tricks/segmentation/readme.rst b/docs/tricks/segmentation/readme.rst
@@ -1,32 +1,43 @@
+###########################
+ Image manipulation tricks
+###########################
 
-*************************
-Image manipulation tricks
-*************************
-
-Segmentation
-============
+**************
+ Segmentation
+**************
 
 Ostu's method
--------------
+=============
+
+.. note::
+
+   **References**
+
+   -  `Implement Otsu's thresholding in Python without using OpenCV and
+      MATLAB
+      <https://www.quora.com/How-do-I-implement-Otsus-thresholding-in-Python-without-using-OpenCV-and-MATLAB-1>`_
 
-.. note:: **References**
+   -  `Scikit's skimage.filters.threshold_otsu
+      <https://github.com/scikit-image/scikit-image/blob/master/skimage/filters/thresholding.py#L230>`_
 
-  *   `Implement Otsu's thresholding in Python without using OpenCV and MATLAB <https://www.quora.com/How-do-I-implement-Otsus-thresholding-in-Python-without-using-OpenCV-and-MATLAB-1>`_
-  *   `Scikit's skimage.filters.threshold_otsu <https://github.com/scikit-image/scikit-image/blob/master/skimage/filters/thresholding.py#L230>`_
-  *   `Scikit's Otsu's thresholding <https://scipy-lectures.org/packages/scikit-image/auto_examples/plot_threshold.html>`_
+   -  `Scikit's Otsu's thresholding
+      <https://scipy-lectures.org/packages/scikit-image/auto_examples/plot_threshold.html>`_
 
 :download:`source: otsu.py <otsu.py>`
 
 .. image:: otsu.svg
-  :width: 800px
-  :align: center
+   :width: 800px
+   :align: center
 
-This example uses Otsu's method to combine two sources (two different images of the same object) to get an optimal threshold. The idea is to get a weighted average of two images as follows
+This example uses Otsu's method to combine two sources (two different
+images of the same object) to get an optimal threshold. The idea is to
+get a weighted average of two images as follows
 
 .. math::
 
-  \mathcal{I}
-  =
-  (1 - \alpha) \mathcal{I}_a + \alpha \mathcal{I}_b
+   \mathcal{I}
+   =
+   (1 - \alpha) \mathcal{I}_a + \alpha \mathcal{I}_b
 
-whereby :math:`\alpha` is chosen such that the separability, defined by Otsu is maximised.
+whereby :math:`\alpha` is chosen such that the separability, defined by
+Otsu is maximised.