POC on styling the doc.

.github/workflows/build_docs.yml

@@ -0,0 +1,45 @@
+name: Build, zip and upload documentation for release
+
+on:
+  release:
+    types:
+      - created
+      - edited 
+  workflow_dispatch:  # This allows manual triggering
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8  # Replace with your desired Python version
+
+      - name: Install dependencies
+        run: |
+          cd docs/sphinx/
+          pip install -r source/requirements.txt  # Replace with your project's requirements file
+
+      - name: Build Sphinx documentation
+        run: |
+          mkdir build/
+          sphinx-build -b html -a -E source/ build/  # Replace with your documentation source and build directories
+
+      - name: Zip Documentation
+        run: |
+          # Create a zip file of the documentation
+          cd build/
+          zip -r SofaPython3_${{ steps.branch_name.outputs.branch_name }}_docs.zip .
+
+      - name: Upload to GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+            SofaPython3_${{ steps.branch_name.outputs.branch_name }}_docs.zip
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.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

.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/

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.12)
 
-project(SofaPython3 VERSION 20.12.00)
+project(SofaPython3 VERSION 24.12.00)
 
 find_package(Sofa.Config REQUIRED)
 

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());
 }

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

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);
 }
 

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

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);

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);
 }

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);
 }
 

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.)

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 *

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
@@ -256,14 +247,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__
 
@@ -295,18 +290,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)
 

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)