Improve documentation and fix compilation issues (#139)

* Udpdate doc

* Update requirements for readthedocs

Co-authored-by: Hugo Talbot <[email protected]>

Author: jnbrunet

.readthedocs.yml

@@ -0,0 +1,24 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+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

bindings/Sofa/CMakeLists.txt

@@ -1,6 +1,6 @@
 project(Bindings.Sofa)
 
-set(SOFABINDINGS_MODULE_LIST Core Components Helper Simulation Types)
+set(SOFABINDINGS_MODULE_LIST Core Helper Simulation Types)
 
 foreach(sofabindings_module ${SOFABINDINGS_MODULE_LIST})
 	add_subdirectory(src/SofaPython3/Sofa/${sofabindings_module})

bindings/Sofa/package/__init__.py

@@ -34,16 +34,17 @@
 import traceback
 import importlib
 
+import Sofa.constants
 import Sofa.Helper
 import Sofa.Core
 import Sofa.Simulation
 import Sofa.Types
-import Sofa.Components
+# import Sofa.Components
 import SofaTypes
 
 from .prefab import *
 
-__all__=["animation", "prefab"]
+__all__=["constants", "Helper", "Core", "Simulation", "Types", "SofaTypes", "prefab"]
 
 # Keep a list of the modules always imported in the Sofa-PythonEnvironment
 try:

bindings/SofaRuntime/src/SofaPython3/SofaRuntime/Timer/Submodule_Timer.cpp

@@ -180,7 +180,7 @@ py::module addSubmoduleTimer(py::module &m)
     timer.def("stepEnd", [](const std::string& id){ AdvancedTimer::stepEnd(id);}, py::arg("id"));
     timer.def("end", [](const std::string& id){ AdvancedTimer::end(id);}, py::arg("id"));
 
-    timer.def("setOutputType", &AdvancedTimer::setOutputType, py::arg("id"), py::arg("newOutputType"), doc::Timer::setOutputType);
+    timer.def("setOutputType", [](const std::string& id, const std::string& type){ AdvancedTimer::setOutputType(id, type);}, py::arg("id"), py::arg("newOutputType"), doc::Timer::setOutputType);
     timer.def("getRecords", &getRecords, py::arg("id"));
 
     return timer;

bindings/SofaRuntime/src/SofaPython3/SofaRuntime/Timer/Submodule_Timer_doc.h

@@ -49,6 +49,9 @@ Sets the interval for the given timer.
 
 static auto setOutputType =
 R"(
-Changes the output type for a given timer.
+Set the outputType for the given AdvancedTimer.
+
+@param id string id of the timer
+@param type string output type name (example : "json")
 )";
 }

docs/CMakeLists.txt

@@ -2,6 +2,7 @@ project(Documentation)
 
 set(DOCUMENTATION_FILES
     ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/source/index.rst
+    ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/source/menu/Compilation.rst
     ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/source/menu/Contributing.rst
     ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/source/menu/SofaPlugin.rst
     ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/source/menu/SofaModule.rst

docs/README.md

@@ -0,0 +1,46 @@
+# Generating the sphinx documentation
+
+The sphinx documentation is automatically built by readthedocs.io when a commit is
+added to the master branch. This readme describes the steps to locally build the
+documentation on your PC. It is written for Ubuntu 20.04, but the steps are very
+similar with other Linux distributions.
+
+### 1. Installing the requirements
+The following dependencies are required:
+
+```shell
+sudo apt install build-essential python3 python3-pip python3-sphinx
+pip3 install --user sphinx_rtd_theme
+```
+
+Go inside the `SofaPython3/docs/sphinx` directory and run
+
+```shell
+pip3 install --user -r source/requirements.txt
+```
+
+### 2. Generating the stubs
+Install the pybind11-stubgen:
+```shell
+python -m pip install git+https://github.com/sizmailov/pybind11-stubgen.git
+```
+
+Make sure python can find SofaPython3 modules, i.e.:
+```shell
+export SOFA_ROOT=/opt/sofa_v20.12/build/install
+export PYTHONPATH="$SOFA_ROOT/plugins/SofaPython3/lib/python3/site-packages"
+```
+
+The following line can be used to make sure Sofa bindings can be found by python:
+```shell
+python -c "import importlib;print('OK') if importlib.util.find_spec('Sofa') else print('NOT OK');"
+```
+
+Go inside the `SofaPython3/docs` directory and run
+```shell
+pybind11-stubgen -o sphinx-stubs --no-setup-py --ignore-invalid=signature --root-module-suffix="" SofaRuntime
+pybind11-stubgen -o sphinx-stubs --no-setup-py --ignore-invalid=signature --root-module-suffix="" Sofa
+pybind11-stubgen -o sphinx-stubs --no-setup-py --ignore-invalid=signature --root-module-suffix="" SofaExporter
+pybind11-stubgen -o sphinx-stubs --no-setup-py --ignore-invalid=signature --root-module-suffix="" SofaTypes
+pybind11-stubgen -o sphinx-stubs --no-setup-py --ignore-invalid=signature --root-module-suffix="" splib
+```