a lot of documentation

modules/python/doc/CMakeLists.txt

@@ -66,7 +66,7 @@ configure_file(
 )
 
 add_custom_target(visp_python_bindings_doc
-  COMMAND ${PYTHON3_EXECUTABLE} -m pip install -r "${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt"
+  COMMAND ${PYTHON3_EXECUTABLE} -m pip install -q -r "${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt"
   COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_CURRENT_SOURCE_DIR}/_static" "${BINARY_BUILD_DIR}/_static"
 	COMMAND ${PYTHON3_EXECUTABLE} -m sphinx
 		-b html

modules/python/doc/api.rst.in

@@ -1,6 +1,14 @@
+.. _API reference:
+
 API reference
 ==============
 
+This API documentation is automatically generated by parsing the C++ documentation.
+
+.. warning::
+
+  Some documentation may be missing, and there may incorrect/missing links. If you are having issues, see the C++ documentation.
+
 
 .. autosummary::
   :toctree: _autosummary

modules/python/doc/conf.py.in

@@ -16,12 +16,8 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 import sys
 import os
-from sphinx.util.logging import *
 
 
-
-sys.path.insert(0, os.path.abspath('../build'))
-
 # If your documentation needs a minimal Sphinx version, state it here.
 # needs_sphinx = '1.0'
 
@@ -35,7 +31,7 @@ extensions = [
     "sphinx.ext.autosummary",
     "sphinx.ext.doctest",
     "sphinx_immaterial",
-    # "sphinx_immaterial.apidoc.python.apigen"
+    "sphinx_design"
 ]
 
 # python_apigen_modules = {
@@ -159,6 +155,7 @@ html_theme_options = {
       "toc.sticky",
       "navigation.instant"
     ],
+    "globaltoc_collapse": False,
     "palette": [
         {
             "media": "(prefers-color-scheme: light)",
@@ -282,7 +279,11 @@ latex_elements = {
     # Latex figure (float) alignment
     #'figure_align': 'htbp',
 }
-
+rst_prolog = """
+.. role:: python(code)
+    :language: python
+    :class: highlight
+"""
 html_logo = '_static/visp_icon_white.png'
 html_favicon = '_static/visp_icon.png'
 
@@ -364,7 +365,7 @@ texinfo_documents = [
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"python": ("https://docs.python.org/", None)}
 
-from sphinx.util.logging import WarningLogRecordTranslator
+from sphinx.util.logging import WarningLogRecordTranslator, WarningStreamHandler
 
 # Filter warning about Parameter names not matching function signature
 # This is somethiing that is due to pybind overloads, so we cannot do anything about it

modules/python/doc/index.rst

@@ -1,16 +1,82 @@
 ViSP Python Documentation
 ============================
 
-Welcome to the ViSP Python binding documentation!
-
-
-
 .. currentmodule:: visp
 
 .. toctree::
-    :glob:
     :maxdepth: 2
+    :hidden:
 
     rst/coming_from_cpp.rst
-    rst/python_api.rst
+    rst/python_api/python_api.rst
+    rst/tutorials/tutorials.rst
+    rst/dev/dev.rst
+    api.rst
     rst/known_issues.rst
+
+
+Welcome to the ViSP Python binding documentation!
+
+  ViSP is a modular C++ library that allows fast development of visual servoing applications.
+  ViSP is developed and maintained by the `Inria Rainbow (former Lagadic) team located <https://team.inria.fr/rainbow/>`_ at Inria Rennes.
+
+
+
+Introduction
+----------------------------
+
+This documentation is specifically aimed at developers choosing to use ViSP in Python.
+
+Other, more general resources, are available:
+
+* If you are using C++, please see `the dedicated documentation <https://visp-doc.inria.fr/doxygen/visp-daily/>`_
+
+* The ViSP wiki can be found `here <https://github.com/lagadic/visp/wiki>`_
+
+* The ViSP source code available on `GitHub <https://github.com/lagadic/visp>`_
+
+* Results and demonstrations can be seen on the `ViSP YouTube channel <https://www.youtube.com/@VispTeam>`_
+
+
+Disclaimer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This documentation does not cover the full capabilities of ViSP. Please see the C++ documentation, which contains:
+
+* `Tutorials <https://visp-doc.inria.fr/doxygen/visp-daily/tutorial_users.html>`_ on:
+
+  * The core concepts: linear algebra, image processing, etc.
+  * Visual servoing with 3D, 2D or photometric features
+  * Object pose estimation and tracking
+
+    * With the model-based tracker (MBT) :py:class:`visp.mbt.MbGenericTracker`
+    * With MegaPose, a deep learning approach to pose estimation :py:class:`visp.dnn_tracker.Megapose`
+
+* `Examples <https://visp-doc.inria.fr/doxygen/visp-daily/examples.html>`_
+
+  * Demonstrating basic feature usage
+  * Servoing on specific robotics platforms
+  * Tracking
+
+
+There are still issues with these generated bindings: see :ref:`Known issues`
+
+
+Getting started
+^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are transitioning from C++, please have a look at the :ref:`CPP guide` to understand the differences between the Python and C++ versions.
+
+
+For general ViSP + Python guidance, see the :ref:`Python API guide`.
+
+
+For tutorials on specific features: see :ref:`Tutorials`.
+
+Finally, if you wish to browse the full ViSP class documentation, go to the :ref:`API reference`.
+
+
+Customizing, extending and contributing to the bindings
+--------------------------------------------------------
+
+If you wish to contribute, extend or modify the bindings for your own needs, please read the :ref:`Development guide`

modules/python/doc/requirements.txt

@@ -1,3 +1,4 @@
 sphinx
 sphinx-immaterial
 sphinxcontrib-jsmath
+sphinx-design

modules/python/doc/rst/coming_from_cpp.rst

@@ -1,2 +1,157 @@
-Differences with the C++
+.. _CPP guide:
+
+Differences with C++ ViSP
 ==============================
+
+In this section, we highlight the differences with writing ViSP code in C++.
+
+Module structure
+-----------------------------
+
+The overall module structure remains the same.
+What was, in C++, referred as :code:`visp3/core/*` can now be accessed as :python:`visp.core.*` in Python.
+Note that before this works in Python, you need to :python:`import visp`
+
+
+Naming convention
+-----------------------------
+
+In C++, each class has the prefix `vp`. In Python, this prefix has been dropped as imports can be aliased and full names can be used.
+
+.. testcode::
+
+  import visp.core
+  from visp.core import Matrix as vpMatrix # if the name clashes with another lib
+
+  m = vpMatrix()
+  vec = visp.core.ColVector(10) # Use the full name, explicit visp use
+
+
+
+Importing a class
+----------------------------
+
+The syntax to import a ViSP class into the current scope is different.
+
+In C++, including a header file pulls everything in it (functions and classes).
+
+
+In the ViSP Python API, no distinction is made between the different headers: everything is at the same level in the package hierarchy.
+In Python, you can import a single symbol.
+
+Thus, if a single header contains two symbols in ViSP, you will need to import both on the Python side.
+
+Below, the difference in syntax between C++ and Python on imports is illustrated:
+
+.. tab-set::
+
+    .. tab-item:: C++
+        :sync: cpp
+
+        .. code-block:: cpp
+
+          #include <visp3/core/vpImageConvert.h>
+          #include <visp3/core/vpColVector.h>
+          #include <visp3/core/vpMatrix.h>
+
+
+    .. tab-item:: Python
+        :sync: python
+
+        .. testcode::
+
+          from visp.core import ImageConvert
+          from visp.core import ColVector, Matrix # Grouping relevant imports
+
+
+You can also import everything from a single submodule:
+
+.. tab-set::
+
+    .. tab-item:: C++
+        :sync: cpp
+
+        .. code-block:: cpp
+
+          #include <visp3/visp_core.h>
+
+
+    .. tab-item:: Python
+        :sync: python
+
+        .. testcode::
+
+          from visp.core import *
+
+
+Changes in function parameters
+--------------------------------------
+
+For some functions, the Python API differs from the C++ one, mainly in the input arguments and return type.
+
+Due to python considering basic types as immutable, it is no longer possible to modify them passing their reference to a function call.
+
+Thus, we have made the choice to modify the functions such that these immutable types, if they are modified, are returned along with the original type.
+
+This encompasses other types, such as lists (std::vector), and dictionaries (maps)
+
+
+Naively translating the use of :code:`convertPoint` from C++:
+
+.. testcode:: error_args
+
+  from visp.core import PixelMeterConversion, CameraParameters
+  cam = CameraParameters(600, 600, 320, 240)
+  u, v = 240, 320
+  x, y = 0, 0
+  PixelMeterConversion.convertPoint(cam, u, v, x, y) # WRONG: C++-like version, using references to modify x and y
+
+Would lead to an error such as:
+
+.. testoutput:: error_args
+  :options: -ELLIPSIS, +NORMALIZE_WHITESPACE, +IGNORE_EXCEPTION_DETAIL
+
+  Traceback (most recent call last):
+    File "<stdin>", line 1, in <module>
+  TypeError: convertPoint(): incompatible function arguments. The following argument types are supported:
+    1. (cam: _visp.core.CameraParameters, u: float, v: float) -> Tuple[float, float]
+    2. (cam: _visp.core.CameraParameters, iP: _visp.core.ImagePoint) -> Tuple[float, float]
+
+  Invoked with: Camera parameters for perspective projection without distortion:
+    px = 600	 py = 600
+    u0 = 320	 v0 = 240
+  , 240, 320, 0, 0
+
+Because this function has been modified to return a tuple of :code:`Tuple[float, float]` (the x and y values).
+The x and y arguments are no longer accepted, as they are output only.
+
+Thus, the correct function call is:
+
+.. testcode:: error_args
+
+  from visp.core import PixelMeterConversion, CameraParameters
+  cam = CameraParameters(600, 600, 320, 240)
+  u, v = 240, 320
+  x, y = PixelMeterConversion.convertPoint(cam, u, v)
+
+
+If you have such errors, it is recommended that you look at the Python :ref:`API reference` for the function and look at its signature.
+
+
+
+.. tab-set::
+
+    .. tab-item:: C++
+        :sync: cpp
+
+        .. code-block:: cpp
+
+          #include <visp3/visp_core.h>
+
+
+    .. tab-item:: Python
+        :sync: python
+
+        .. testcode::
+
+          from visp.core import *

modules/python/doc/rst/dev/config.rst

@@ -0,0 +1,2 @@
+Configuration files
+====================

modules/python/doc/rst/dev/custom_bindings.rst

@@ -0,0 +1,2 @@
+Adding a custom function binding
+=================================

modules/python/doc/rst/dev/dev.rst

@@ -0,0 +1,13 @@
+.. _Development guide:
+
+Modifying and contributing to the bindings
+====================
+
+.. toctree::
+    :glob:
+    :maxdepth: 2
+
+    how.rst
+    config.rst
+    custom_bindings.rst
+    python_side.rst

modules/python/doc/rst/dev/how.rst

@@ -0,0 +1,2 @@
+How bindings are generated
+===========================

modules/python/doc/rst/dev/python_side.rst

@@ -0,0 +1,2 @@
+Adding a Python side improvement
+=================================

modules/python/doc/rst/known_issues.rst

@@ -1,7 +1,24 @@
-List of todos
+.. _Known issues:
+
+Known issues
 ======================
 
-What remains to be done
+We are aware of some issues remaining
+
+
+No implicit conversion from ViSP types to Numpy
+-------------------------------------------------
+
+
+ViSP 3rd party types (such as cv::Mat) cannot be used from Python
+-------------------------------------------------
+
+Cannot inherit from ViSP
+------------------------------------------------
+
+
+
+
 
 Changes to ViSP
 ------------------

modules/python/doc/rst/python_api/conversions.rst

@@ -99,7 +99,7 @@ Thus, this code will not work:
   ValueError: assignment destination is read-only
 
   >>> T = HomogeneousMatrix()
-  >>> R.numpy()[0, 1] = 1.0
+  >>> T.numpy()[0, 1] = 1.0
   Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
   ValueError: assignment destination is read-only