Updated version of documentation (#449)

* Remove the automock of Sofa * WIPPP * WIP * WIP2 * Remove sphinx-stubs as don't need them anymore. * FIX Documentation * W * WIP * WIP * W * WIP * W * W * W * W * W * W * D * review and clean of documentation * Update requirements for automatization * Add action to generate doc on new release * Up * Clean code, format and add full documentation * Add as a trigger of action the edit of a release * FIX * Various documentation fixes. * Refactor the documentation organization & sections & subsection so the menu looks ok * Last improvements before upload * We shouldent import scipy for our users. They are competent enough * FIX * Fix broken tests. * Remove an introduced change in SofaRuntime. * Update .github/workflows/build_docs.yml Co-authored-by: Hugo <[email protected]> * Update CMakeLists.txt Co-authored-by: Hugo <[email protected]> * Delete .github/workflows/build_docs.yml --------- Co-authored-by: Hugo Talbot <[email protected]>
sofa-framework · Nov 19, 2024 · d98fb54 · d98fb54
1 parent 277fc66
commit d98fb54
Show file tree

Hide file tree

Showing 110 changed files with 1,702 additions and 6,891 deletions.
diff --git a/.gitignore b/.gitignore
@@ -5,6 +5,7 @@
 __pycache__/
 *.pyc
 *.so
-docs/stubs
-docs/sphinx/build/
-docs/sphinx/source/*/_autosummary*
+docs/sphinx/build/*
+docs/sphinx/source/*/generated
+docs/sphinx/source/*/*/generated
+docs/sphinx/source/*/*/*/generated
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -9,16 +9,10 @@ version: 2
 sphinx:
   configuration: docs/sphinx/source/conf.py
 
-# Build documentation with MkDocs
-#mkdocs:
-#  configuration: mkdocs.yml
-
-# Optionally build your docs in additional formats such as PDF
-formats:
-  - pdf
-
-# Optionally set the version of Python and requirements required to build your docs
-python:
-  version: 3.7
-  install:
-    - requirements: docs/sphinx/source/requirements.txt
+build:
+  os: "ubuntu-22.04"
+  commands:
+    - mkdir --parents $READTHEDOCS_OUTPUT/html/
+    - wget https://github.com/sofa-framework/SofaPython3/releases/download/release-v23.06/SofaPython3_v23.06_docs.zip
+    - unzip SofaPython3_v23.06_docs.zip
+    - cp --recursive build/html/* $READTHEDOCS_OUTPUT/html/
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.12)
 
-project(SofaPython3 VERSION 20.12.00)
+project(SofaPython3 VERSION 24.12.99)
 
 find_package(Sofa.Config REQUIRED)
 

diff --git a/Plugin/src/SofaPython3/Prefab.cpp b/Plugin/src/SofaPython3/Prefab.cpp
@@ -68,7 +68,6 @@ void Prefab::reinit()
 
     doReInit();
 
-    /// Beurk beurk beurk
     sofa::simulation::node::init(this);
     execute<VisualInitVisitor>(sofa::core::visual::visualparams::defaultInstance());
 }

diff --git a/bindings/Modules/src/SofaPython3/SofaBaseTopology/Module_SofaBaseTopology.cpp b/bindings/Modules/src/SofaPython3/SofaBaseTopology/Module_SofaBaseTopology.cpp
@@ -32,10 +32,12 @@ namespace sofapython3
 
 PYBIND11_MODULE(SofaBaseTopology, m)
 {
+    m.doc() = "Implements some topology component (Regular and SparseGridTopology)";
+
     sofa::component::topology::container::grid::init();
 
     moduleAddRegularGridTopology(m);
     moduleAddSparseGridTopology(m);
 }
 
-} // namespace sofapython3
+} // namespace sofapython3
diff --git a/bindings/Modules/src/SofaPython3/SofaConstraintSolver/Module_SofaConstraintSolver.cpp b/bindings/Modules/src/SofaPython3/SofaConstraintSolver/Module_SofaConstraintSolver.cpp
@@ -26,6 +26,8 @@ namespace sofapython3
 
 PYBIND11_MODULE(SofaConstraintSolver, m)
 {
+    m.doc() = "Implements the solver for constraint problems";
+
     moduleAddConstraintSolver(m);
 }
 

diff --git a/bindings/Modules/src/SofaPython3/SofaDeformable/Binding_LinearSpring_doc.h b/bindings/Modules/src/SofaPython3/SofaDeformable/Binding_LinearSpring_doc.h
@@ -24,12 +24,13 @@ namespace sofapython3::doc::SofaDeformable {
 
 static auto LinearSpringClass =
 R"(
-A LinearSpring between two objects, specified by indices on a topology.
+A linear spring connecting pair of nodes of two different objects
 )";
 
 static auto LinearSpringInit =
 R"(
 Create a linear spring from indices and spring parameters.
+
 :param index1: Index of the point on object 1.
 :param index2: Index of the point on object 2.
 :param springStiffness: Stiffnes k of the spring (f = -k*x -d*v)
@@ -39,6 +40,7 @@ Create a linear spring from indices and spring parameters.
 :param enabled: If set to false, no force will be calculated for this spring
 
 :return: A linear spring of type Sofa.SofaDeformable.LinearSpring
+
 )";
 
 } // sofapython3::doc::SofaDeformable
diff --git a/bindings/Modules/src/SofaPython3/SofaDeformable/Binding_SpringForceField.cpp b/bindings/Modules/src/SofaPython3/SofaDeformable/Binding_SpringForceField.cpp
@@ -47,7 +47,9 @@ void bindSpringForcefield(py::module& m) {
 
     // create a python binding for the c++ class SpringForceField from SofaDeformable
     // no init binding, because creation should be done via node.addObject("SpringForceField")
-    std::string type_name = sofa::helper::NameDecoder::getTypeName<SpringForceField>();
+    std::string type_name = SpringForceField::GetClass()->className+"_"+
+                            DataType::Name();
+
     py::class_<SpringForceField,
             sofa::core::objectmodel::BaseObject,
             py_shared_ptr<SpringForceField>> s (m, type_name.c_str(), sofapython3::doc::SofaDeformable::SpringForceFieldClass);

diff --git a/bindings/Modules/src/SofaPython3/SofaDeformable/Module_SofaDeformable.cpp b/bindings/Modules/src/SofaPython3/SofaDeformable/Module_SofaDeformable.cpp
@@ -30,6 +30,8 @@ namespace sofapython3
 
 PYBIND11_MODULE(SofaDeformable, m)
 {
+    m.doc() = "Implements linear springs between objects";
+
     moduleAddLinearSpring(m);
     moduleAddSpringForceField(m);
 }

diff --git a/bindings/Modules/src/SofaPython3/SofaGL/Module_SofaGL.cpp b/bindings/Modules/src/SofaPython3/SofaGL/Module_SofaGL.cpp
@@ -29,6 +29,8 @@ namespace sofapython3
 
 PYBIND11_MODULE(SofaGL, m)
 {
+    m.doc() = "Exposes the rendering API using OpenGL";
+
     moduleAddDrawToolGL(m);
 }
 

diff --git a/bindings/Sofa/package/PyTypes/Vec3.py b/bindings/Sofa/package/PyTypes/Vec3.py
@@ -29,7 +29,7 @@ class Vec3(numpy.ndarray):
     def __new__(cls, *args):
         """ Vec3 constructor expects zero, one or three arguments.
 
-        Examples:
+        Example:
 
         >>> v = Vec3()
         >>> print(v)
@@ -125,7 +125,7 @@ def normalize(self, *args):
     def translate(self, *args):
         """ Function translate of class Vec3 expects one or three arguments. Note that you can also use the '+' and '-' operators.
 
-        Examples:
+        Example:
 
         >>> v = Vec3([0.,0.,0.])
         >>> v.translate(1.)
@@ -209,7 +209,7 @@ def rotateFromAxisAngle(self, axis, angle):
     def scale(self, *args):
         """ Function scale of class Vec3 expects one or three arguments. Note that you can also use the '*' and '/' operators.
 
-        Examples:
+        Example:
 
         >>> v = Vec3([1.,2.,3.])
         >>> v.scale(2.)

diff --git a/bindings/Sofa/package/PyTypes/__init__.py b/bindings/Sofa/package/PyTypes/__init__.py
@@ -1,11 +1,8 @@
 """
 Data types
------------------------
+----------
 
-.. autosummary::
- Sofa.Types.RGBAColor
- Sofa.Types.Vec3
 """
 
 from .Vec3 import *
-from .RGBAColor import *
+from .RGBAColor import *
diff --git a/bindings/Sofa/package/__init__.py b/bindings/Sofa/package/__init__.py
@@ -1,8 +1,7 @@
 """
-Package containing the binding for the core of Sofa
--------------------------------------------------
+All SOFA key components supported by the SOFA consortium
 
-Example of use:
+Example:
   .. code-block:: python
 
     import Sofa.Core
@@ -17,14 +16,6 @@
     Sofa.Simulation.init(n)
     Sofa.Simulation.print(n)
 
-Submodules:
-  .. autosummary::
-    :toctree: _autosummary
-
-    Sofa.Core
-    Sofa.Simulation
-    Sofa.Types
-    Sofa.Helper
 """
 
 import sys
@@ -255,14 +246,18 @@ def getSofaFormattedStringFromException(e):
 
 def sofaExceptHandler(type, value, tb):
     global oldexcepthook
-    """This exception handler, convert python exceptions & traceback into more classical sofa error messages of the form:
-       Message Description
-       Python Stack (most recent are at the end)
-          File file1.py line 4  ...
-          File file1.py line 10 ...
-          File file1.py line 40 ...
-          File file1.py line 23 ...
-            faulty line
+    """This exception handler converts python exceptions & traceback into classical SOFA error messages
+
+       Message:
+
+        .. code-block:: text
+
+            Python Stack (most recent are at the end)
+            File file1.py line 4  ...
+            File file1.py line 10 ...
+            File file1.py line 40 ...
+            File file1.py line 23 ...
+
     """
     h = type.__name__
 
@@ -294,18 +289,26 @@ def pyType2sofaType(v):
 
 
 def msg_error(target, message):
+    """API emitting error messages
+    """
     frameinfo = inspect.getframeinfo(inspect.currentframe().f_back)
     Sofa.Helper.msg_error(target, message, frameinfo.filename, frameinfo.lineno)
 
 def msg_info(target, message):
+    """API emitting information messages
+    """
     frameinfo = inspect.getframeinfo(inspect.currentframe().f_back)
     Sofa.Helper.msg_info(target, message, frameinfo.filename, frameinfo.lineno)
 
 def msg_warning(target, message):
+    """API emitting warning messages
+    """
     frameinfo = inspect.getframeinfo(inspect.currentframe().f_back)
     Sofa.Helper.msg_warning(target, message, frameinfo.filename, frameinfo.lineno)
 
 def msg_deprecated(target, message):
+    """API emitting deprecation messages
+    """
     frameinfo = inspect.getframeinfo(inspect.currentframe().f_back)
     Sofa.Helper.msg_deprecated(target, message, frameinfo.filename, frameinfo.lineno)
 

diff --git a/bindings/Sofa/package/prefab.py b/bindings/Sofa/package/prefab.py
@@ -1,53 +1,56 @@
+"""
+Prefabs are python templates for a SOFA scene
+"""
+
 import Sofa.Core
 import inspect
 import os
 
 
 class Prefab(Sofa.Core.RawPrefab):
-    """
-    Special Node to make reusable procedural objects in Sofa.
-    ---------------------------------------------------------
 
-    Inherit from this class to create your own Prefab. What makes Prefab special is that they 
-    have a set of special data named prefabParameters. When any of prefabParameter is changed the prefab
-    is completely recreated by calling the onParameterChanged method so the scene graph is always kept synchronized
-    with the parameter's content.
+    def __init__(self, *args, **kwargs):
+        """
+        Prefabs are python templates for a SOFA scene
 
-    To specify the prefabParameters, it is possible to provide in the class a list of dictionaries containing the 3 required fields ("name", "type", "help")
-    and one optional field ("default").
+        They allow to simplify the design of a simulation by using pre-structured and reusable python script.
+        Inherit from this class to create your own Prefab. What makes Prefab special is that they
+        have a set of special data named prefabParameters. When any of prefabParameter is changed the prefab
+        is completely recreated by calling the onParameterChanged method so the scene graph is always kept synchronized
+        with the parameter's content.
 
-    The same syntax can be used to also add prefab's data.
+        To specify the prefabParameters, it is possible to provide in the class a list of dictionaries containing the 3 required fields ("name", "type", "help")
+        and one optional field ("default").
 
-    Example of use:
-      .. code-block:: python
+        The same syntax can be used to also add prefab's data.
 
-        import Sofa.Core
+        Example:
+          .. code-block:: python
 
-        class Foo(Sofa.Core.Prefab):
-            prefabParameters = [{ 'name': 'n', 'type': 'int', 'help': 'number of repetition, 'default': 1},
-                                {'name': 'message', 'type': 'string', 'help': 'message to display', 'default': ''}]
+            import Sofa.Core
 
-            myAttribute = 0
+            class Foo(Sofa.Core.Prefab):
+                prefabParameters = [{ 'name': 'n', 'type': 'int', 'help': 'number of repetition, 'default': 1},
+                                    {'name': 'message', 'type': 'string', 'help': 'message to display', 'default': ''}]
 
-            def __init__(self, *a, *k):
-                Sofa.Core.Prefab.__init__(self, *a, **k)
+                myAttribute = 0
 
-            def init(self):
-                myAttribute += 1
-                for i in range(0, self.n.value):
-                    print(self.message.value)
+                def __init__(self, *a, *k):
+                    Sofa.Core.Prefab.__init__(self, *a, **k)
 
-        n = Sofa.Core.Node()
-        n.addChild(Foo(name="aFooPrefab", n=42, message="hello universe!"))
+                def init(self):
+                    myAttribute += 1
+                    for i in range(0, self.n.value):
+                        print(self.message.value)
 
-    Prefab has protected the following additional keywords:
-        - "name": the name of the prefab instance
-        - "parent" and "parents": can't be used together, they set the context of the prefab,
-           thus allowing paths resolution for Prefab parameters whose arguments are passed as link paths (strings). parents (with an '-s') sets multi-node contexts
+            n = Sofa.Core.Node()
+            n.addChild(Foo(name="aFooPrefab", n=42, message="hello universe!"))
 
+        Prefab has protected the following additional keywords:
+            - "name" = the name of the prefab instance
+            - "parent" and "parents" = can't be used together, they set the context of the prefab, thus allowing paths resolution for Prefab parameters whose arguments are passed as link paths (strings). parents (with an '-s') sets multi-node contexts
+        """
 
-    """
-    def __init__(self, *args, **kwargs):
         Sofa.Core.RawPrefab.__init__(self, *args, **kwargs)
         frame = inspect.currentframe().f_back
         frameinfo = inspect.getframeinfo(frame)

diff --git a/bindings/Sofa/src/SofaPython3/Sofa/Core/Binding_BaseCamera_doc.h b/bindings/Sofa/src/SofaPython3/Sofa/Core/Binding_BaseCamera_doc.h
@@ -24,10 +24,9 @@ namespace sofapython3::doc::baseCamera {
 
 static auto baseCameraClass =
         R"(
-        Camera is an API dedicated to the control of the Camera in SOFA.
-
-        :Example of use:
+        API dedicated to the control of the Camera in SOFA
 
+        Example:
         .. code-block:: python
 
             import Sofa.Core
@@ -47,7 +46,7 @@ static auto baseCameraClass =
         ctrl+x to move backward, ctrl+d to translate on the right, ctrl+q to translate on the left.
         The code for this example is available in the folder examples under the name BaseCamera.py of the SofaPython3 GitHub repository.
 
-        .. image:: ../../../../../images/baseCamera.gif
+        .. image:: ../../../../../../docs/sphinx/source/images/baseCamera.gif
             :alt: Example of a controller for a BaseCamera
             :align: center
             :height: 250pt

diff --git a/bindings/Sofa/src/SofaPython3/Sofa/Core/Binding_BaseContext.cpp b/bindings/Sofa/src/SofaPython3/Sofa/Core/Binding_BaseContext.cpp
@@ -34,7 +34,7 @@ using namespace sofa::core::objectmodel;
 namespace sofapython3 {
 
 void moduleAddBaseContext(py::module& m) {
-    py::class_<BaseContext, Base, py_shared_ptr<BaseContext>> c (m, "BaseContext");
+    py::class_<BaseContext, Base, py_shared_ptr<BaseContext>> c (m, "BaseContext", "Base class for Context classes, storing shared variables and parameters");
 
     py::enum_<BaseContext::SearchDirection>(c, "SearchDirection")
         .value("SearchUp",      BaseContext::SearchDirection::SearchUp)

diff --git a/bindings/Sofa/src/SofaPython3/Sofa/Core/Binding_BaseData_doc.h b/bindings/Sofa/src/SofaPython3/Sofa/Core/Binding_BaseData_doc.h
@@ -24,7 +24,7 @@ namespace sofapython3::doc::baseData
 {
 static auto BaseDataClass =
         R"(
-        The purpose of a data is to store the attributs of your component.
+        Public attribute of a Component (C++ class) visible and accessible to the user (read/write)
 
         :Create a data field:
 

diff --git a/bindings/Sofa/src/SofaPython3/Sofa/Core/Binding_BaseLink_doc.h b/bindings/Sofa/src/SofaPython3/Sofa/Core/Binding_BaseLink_doc.h
@@ -24,11 +24,12 @@ namespace sofapython3::doc::baseLink
 {
 static auto baseLinkClass =
         R"(
+        Connection created between Data instances of two different Components
+
         A Link allows you to access a sofa component from another one anywhere in the simulation graph.
         In your scene creation file, it usually appear as : input=@../component.
 
-        :Example of use:
-
+        Example:
         .. code-block:: python
 
             import Sofa.Core
-Original file line number
+Diff line change
@@ Expand Up / @@ -26,6 +26,8 @@ namespace sofapython3 @@
     PYBIND11_MODULE(SofaConstraintSolver, m)
     {
+        m.doc() = "Implements the solver for constraint problems";
         moduleAddConstraintSolver(m);
     }
@@ Expand Down @@