[doc] updated manual (transition v1 .. v2)

doc/CMakeLists.txt

@@ -88,7 +88,7 @@ install(FILES ${CMAKE_CURRENT_BINARY_DIR}/mathjax_stmaryrd.js
     if(WIN32)
       set(SPHINX_EXECUTABLE "sphinx-build")
     else()
-      set(SPHINX_EXECUTABLE "python3.6" "-msphinx") # todo: replace python3.6 by python3
+      set(SPHINX_EXECUTABLE "python3" "-msphinx")
     endif()
 
     add_custom_target(doc

doc/doc/conf.py.in

@@ -63,6 +63,9 @@ rst_prolog = """
   :class: underline
 .. role:: right-aligned-note
   :class: right-aligned-note
+
+.. seealso::
+  This manual refers to Codac v1, but a new v2 implementation is currently in progress... an update of this manual will be available soon. `See more <https://github.com/codac-team/codac/tree/codac2>`_.
 """
 
 # GitHub repo

doc/doc/install/01-installation-full-linux.rst

@@ -2,23 +2,23 @@
 
 .. _sec-installation-full-linux:
 
-#####################################
-Installing Codac on Linux for C++ use
-#####################################
+########################################
+Installing Codac v1 on Linux for C++ use
+########################################
 
 
 Install from package (latest release, for Ubuntu (amd64, arm64), Debian (arm64, armhf) and possibly others)
 -----------------------------------------------------------------------------------------------------------
 
-A Debian package is available for the last release |version| of the library:
+A Debian package is available for the last release 1.5.6 of the library:
 
 .. code-block:: bash
 
   sudo sh -c 'echo "deb [trusted=yes] https://packages.ensta-bretagne.fr/$(if [ -z "$(. /etc/os-release && echo $UBUNTU_CODENAME)" ]; then echo debian/$(. /etc/os-release && echo $VERSION_CODENAME); else echo ubuntu/$(. /etc/os-release && echo $UBUNTU_CODENAME); fi) ./" > /etc/apt/sources.list.d/ensta-bretagne.list'
   sudo apt update
   sudo apt install libcodac-dev
 
-Then, check your installation `with the instructions of this page <03-start-cpp-project.html>`_.
+Then, check your installation :ref:`with the instructions of this page <sec-start-cpp-project>`.
 
 .. warning::
 
@@ -47,8 +47,8 @@ Then, check your installation `with the instructions of this page <03-start-cpp-
   and check that "My first tube:Tube [0, 10]" appears.
 
 
-Install from sources (latest development)
------------------------------------------
+Install from sources (latest development of v1)
+-----------------------------------------------
 
 In case you prefer the latest development version, Codac can be installed by compiling the sources.
 
@@ -100,6 +100,7 @@ The last sources are available on `the official Codac development repository <ht
   # The codac directory can be placed in your home, same level as IBEX
   git clone https://github.com/codac-team/codac   # download the sources from GitHub
   cd codac                                        # move to the Codac directory
+  git checkout codac1                             # will use latest version of Codac1
   git submodule init ; git submodule update       # get pybind11 submodule
   mkdir build ; cd build ; cmake .. ; make        # build the sources
   sudo make install                               # install the library
@@ -118,7 +119,7 @@ For instance:
   mkdir build -p ; cd build ; cmake .. ; make     # cmake compilation
   ./codac_basics_01                               # running example
 
-Do not forget to launch the `VIBes viewer <01-installation.html#graphical-tools>`_ before running your program.
+Do not forget to launch the :ref:`VIBes viewer <sec-installation-graphics>` before running your program.
 
 
 (for experts) Additional installation options
@@ -179,4 +180,4 @@ Do not forget to launch the `VIBes viewer <01-installation.html#graphical-tools>
     export CMAKE_PREFIX_PATH=$CMAKE_PREFIX_PATH:$HOME/ibex-lib/build_install
     export CMAKE_PREFIX_PATH=$CMAKE_PREFIX_PATH:$HOME/codac/build_install
 
-See also `Information for developers </dev/info_dev.html>`_.
+See also :ref:`Information for developers <sec-manual-dev>`.

doc/doc/install/01-installation-full-macos.rst

@@ -2,9 +2,9 @@
 
 .. _sec-installation-full-macos:
 
-#####################################
-Installing Codac on macOS for C++ use
-#####################################
+########################################
+Installing Codac v1 on macOS for C++ use
+########################################
 
 
 Quick start
@@ -18,7 +18,7 @@ Install `Homebrew package manager <https://brew.sh/>`_ and build tools:
   brew install wget autoconf automake libtool
   brew install --cask cmake
 
-Download and extract *e.g.* ``codac_standalone_arm64_monterey.zip`` (for macOS 12 Monterey on a Mac with Apple silicon (arm64 processor), use ``codac_standalone_x86_64_monterey.zip`` for a Mac with an Intel processor (x86_64 processor), see https://support.apple.com/en-us/116943) from `<https://github.com/codac-team/codac/releases/latest/>`_, then in ``example`` folder run:
+Download and extract *e.g.* ``codac_standalone_arm64_monterey.zip`` (for macOS 12 Monterey on a Mac with Apple silicon (arm64 processor), use ``codac_standalone_x86_64_monterey.zip`` for a Mac with an Intel processor (x86_64 processor), see https://support.apple.com/en-us/116943) from `<https://github.com/codac-team/codac/releases/tag/v1.5.6/>`_, then in ``example`` folder run:
 
 .. code-block:: bash
 
@@ -47,4 +47,4 @@ Optionally, for Python and documentation:
   python -m pip install --upgrade pip
   pip install --upgrade wheel setuptools sphinx breathe sphinx-issues sphinx-tabs sphinx_rtd_theme sphinx-reredirects
 
-The logic to follow will then be similar to `Linux <01-installation-full-linux.html>`_. See also `Information for developers </dev/info_dev.html>`_.
+The logic to follow will then be similar to :ref:`Linux <sec-installation-full-linux>`. See also :ref:`Information for developers <sec-manual-dev>`.

doc/doc/install/01-installation-full-windows.rst

@@ -2,9 +2,9 @@
 
 .. _sec-installation-full-windows:
 
-#######################################
-Installing Codac on Windows for C++ use
-#######################################
+##########################################
+Installing Codac v1 on Windows for C++ use
+##########################################
 
 
 Quick start
@@ -17,7 +17,7 @@ Check https://community.chocolatey.org/packages/codac.
 
 .. rubric:: Using Visual Studio
 
-Download and extract *e.g.* ``codac_standalone_x64_vc17.zip`` (for Visual Studio 2022) from `<https://github.com/codac-team/codac/releases/latest/>`_, open ``example\CMakelists.txt``, choose ``x64-Release`` configuration in Visual Studio (instead of ``x64-Debug``), double-click on ``main.cpp`` in the Solution Explorer and then click on the green Start button, finally check that "My first tube:Tube [0, 10]" appears.
+Download and extract *e.g.* ``codac_standalone_x64_vc17.zip`` (for Visual Studio 2022) from `<https://github.com/codac-team/codac/releases/tag/v1.5.6>`_, open ``example\CMakelists.txt``, choose ``x64-Release`` configuration in Visual Studio (instead of ``x64-Debug``), double-click on ``main.cpp`` in the Solution Explorer and then click on the green Start button, finally check that "My first tube:Tube [0, 10]" appears.
 
 Optionally, download and run `<https://github.com/ENSTABretagneRobotics/VIBES/releases/download/0.2.3/VIBes-0.2.3-win32.exe>`_ before running the project, and check that a tube appears in :ref:`VIBes viewer <sec-installation-graphics>`.
 
@@ -43,7 +43,7 @@ Optionally, for Python (*e.g.* ``choco install python --version=3.10.4``) and do
   python -m pip install --upgrade pip
   pip install --upgrade wheel setuptools sphinx breathe sphinx-issues sphinx-tabs sphinx_rtd_theme sphinx-reredirects
 
-The logic to follow will then be similar to `Linux <01-installation-full-linux.html>`_ (note that for Visual Studio, commands such as ``make install`` need to be replaced with something similar to:
+The logic to follow will then be similar to :ref:`Linux <sec-installation-full-linux>` (note that for Visual Studio, commands such as ``make install`` need to be replaced with something similar to:
 
 .. code-block:: bash
 
@@ -53,4 +53,4 @@ The logic to follow will then be similar to `Linux <01-installation-full-linux.h
 
   | You might need to replace all occurences of :literal:`PATH_SUFFIXES \ ` with something similar to :literal:`PATHS ${CMAKE_CURRENT_LIST_FILE}/../../../../ PATH_SUFFIXES \ ` in all ``.cmake`` in ``codac/share/codac/cmake/`` (where Codac was installed) if a CMake project that tries to use Codac appears to find its installation location but fails to configure the project properly.
 
-See also `Information for developers </dev/info_dev.html>`_.
+See also :ref:`Information for developers <sec-manual-dev>`.

doc/doc/install/01-installation-python.rst

@@ -2,9 +2,9 @@
 
 .. _sec-installation-py:
 
-###############################
-Installing Codac for Python use
-###############################
+##################################
+Installing Codac v1 for Python use
+##################################
 
 .. note::
 
@@ -19,7 +19,8 @@ In case you want to use Codac only with Python, then the installation procedure
   
   # You may have to upgrade pip (19.0.0 required at least)
   pip3 install --upgrade pip 
-  pip3 install codac
+  pip3 install codac==1.5.6
+  # latest release of Codac v1 is 1.5.6
 
 
 .. role:: gbg
@@ -78,7 +79,7 @@ If a configuration in this table does not work, please `contact us <https://gith
 
 .. note::
 
-  Unsupported computers can still probably follow `Installing local Python binding <../dev/info_dev.html>`_ .
+  Unsupported computers can still probably follow :ref:`Installing local Python binding <sec-manual-dev>`.
 
 
 Update your Codac Python package

doc/doc/tutorial/01-basics/index.rst

@@ -1,13 +1,13 @@
 .. _sec-tuto-01:
 
+Lesson A: Getting started with intervals and contractors
+========================================================
+
 .. # define a hard line break for HTML
 .. |br| raw:: html
 
    <br />
 
-Lesson A: Getting started with intervals and contractors
-========================================================
-
 Now that Codac has been installed on your computer or usable online, we will get used to intervals, constraints and networks of contractors.
 This will allow you to perform the state estimation of a static robot between some landmarks by the end of :ref:`Lesson B <sec-tuto-02>`.
 

doc/doc/tutorial/05-tubes/index.rst

@@ -299,7 +299,7 @@ For instance, one can contract three tubes :math:`[a](\cdot)`, :math:`[b](\cdot)
     \mathbf{y}(t)=\mathbf{g}\big(\mathbf{x}(t)\big) &  & \textrm{(observation equation)}
     \end{array}\right.
 
-  **E.10.** We first focus on the observation equation :math:`\mathbf{y}(t)=\mathbf{g}\big(\mathbf{x}(t)\big)`. Build a contractor network and contract the tube :math:`[\mathbf{x}](\cdot)` with the distance contractor, that expresses :math:`\mathbf{g}`. Note that this contractor is already defined in the library. You developed your own version as an exercise in :ref:`sec-tuto-01`, but you can also use:
+  **E.10.** We first focus on the observation equation :math:`\mathbf{y}(t)=\mathbf{g}\big(\mathbf{x}(t)\big)`. Build a contractor network and contract the tube :math:`[\mathbf{x}](\cdot)` with the distance contractor, that expresses :math:`\mathbf{g}`. Note that this contractor is already defined in the library. You developed your own version as an exercise in :ref:`Lesson A <sec-tuto-01>`, but you can also use:
 
   .. tabs::