diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index f338be8cb..23b529fd7 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -2,7 +2,7 @@ project(Documentation) set(DOCUMENTATION_FILES ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/source/index.rst - ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/source/menu/install.rst + ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/source/menu/Installation.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 diff --git a/docs/sphinx/source/_templates/layout.html b/docs/sphinx/source/_templates/layout.html new file mode 100644 index 000000000..f4d402fe0 --- /dev/null +++ b/docs/sphinx/source/_templates/layout.html @@ -0,0 +1,6 @@ +{% extends "!layout.html" %} + +{% block menu %} +Overview +{{ super() }} +{% endblock %} \ No newline at end of file diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 31ead1f98..e12206cd3 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -34,20 +34,18 @@ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.autosummary', - #'sphinx.ext.intersphinx', - #'sphinx.ext.mathjax', - #'sphinx.ext.ifconfig', + 'sphinxcontrib.contentui', 'sphinx.ext.viewcode', 'sphinx.ext.githubpages', 'sphinx.ext.napoleon', - #'autoapi.sphinx', - #'sphinx.ext.inheritance_diagram' ] #autoapi_modules = {'Sofa': None, 'Sofa.Core' : None} import sys import os +import re + #sys.path.append("/home/dmarchal/projects/DEFROST/dev/sofa2/builds/release/lib/site-packages/") sys.path.append(os.getcwd()+"/../../sphinx-stubs") print(sys.path) @@ -74,17 +72,28 @@ # General information about the project. project = u'SofaPython3' -copyright = u'2018, damien.marchal@univ-lille.fr' -author = u'damien.marchal@univ-lille.fr' +copyright = u'2020, SOFA Framework' +author = u'consortium@sofa-framework.org' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = u'1.0' +_cmake_version_re = re.compile(r'project[^\S\n]*\(\w*[^\S\n]*VERSION[^\S\n]+(\w+).(\w+).(\w+)[^\S\n]*\)') + +version_major = 0 +version_minor = 0 +version_patch = 0 +for line in open('../../../CMakeLists.txt'): + version = _cmake_version_re.search(line) + if version: + version_major, version_minor, version_patch = version.group(1), version.group(2), version.group(3) + break + +version = f'{version_major}.{version_minor}' # The full version, including alpha/beta/rc tags. -release = u'1.0' +release = f'{version}.{version_patch}' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -125,7 +134,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = [] # Custom sidebar templates, must be a dictionary that maps document names # to template names. diff --git a/docs/sphinx/source/images/cmake_activate_sp3.jpg b/docs/sphinx/source/images/cmake_activate_sp3.jpg new file mode 100644 index 000000000..97d5d1a83 Binary files /dev/null and b/docs/sphinx/source/images/cmake_activate_sp3.jpg differ diff --git a/docs/sphinx/source/images/cmake_fetch_sp3.jpg b/docs/sphinx/source/images/cmake_fetch_sp3.jpg new file mode 100644 index 000000000..454beee2b Binary files /dev/null and b/docs/sphinx/source/images/cmake_fetch_sp3.jpg differ diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 8dd7cd83a..e9d789cbe 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -1,93 +1,39 @@ -Welcome to SofaPython3 ! -======================== - -The project is python3 binding for the Sofa simulation framework. -It is composed of one *Sofa plugin* and several *python modules*. - -*Sofa plugin* embeds a python3 interpreter and a scene loader. This plugins allows you to load -a python interpreter in a sofa simulation to write Sofa scene directly using python. It also -permits to implement in python3 custom sofa component like ForceField, Controllers, Visitors. - -Apart from the SofaPython3 plugin we also provide several *python modules* that exposes python different -parts of Sofa. - -The general guidelines design for these binding was to be as much as possible idiomatic python3 API -and with tight integration for numpy. - General overview ------------------ -The Sofa python module: -^^^^^^^^^^^^^^^^^^^^^^^ -Exposes the base Sofa object to build and manipulate a Sofa simulation. - -- contains 4 submodules : - - Sofa.Core, that contains bindings for scene components, - - Sofa.Simulation, that contains functions to conduct simulation, - - Sofa.Types, that contains default types available in Sofa, - - Sofa.Helper, that contains utility functions. -- provides a copy-less API to access the sofa Data containers -- allows to implement custom sofa object (ForceField, Controller) in python -- has docstring documentation - -Try it: ```python import Sofa``` - -The SofaRuntime python module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- access the runtime specific stuff (GUI, GLViewers, runSofa internal status) [POC] -- docstring with sphinx content [TBD] - -Try it: ```python import SofaRuntime``` +================ -Developer's environment -^^^^^^^^^^^^^^^^^^^^^^^ -- autogenerated documentation using sphinx [DONE] -- automated update the docs from the c++'s docstring: https://sofapython3.readthedocs.io/en/latest/ [WIP] -- code completion with common editor [WIP, some editor are not working with c++ modules] +The SofaPython3 project brings python bindings for the `SOFA simulation framework `_. +Thereby, it allows users to use most of the components and features found in SOFA directly into their python scripts. +This project is composed of two modules: a *SOFA plugin* and several *python modules*. -Execution environment -^^^^^^^^^^^^^^^^^^^^^ -- SofaPython3 is a plugin to include a python3 environment in a Sofa scene [DONE], +1. The **SofaPython3 plugin** embeds a python interpreter and a SOFA scene loader. This plugin allows one to load a python +script as the main simulation scene file. The scene loader will automatically detect the ".py", ".py3", ".py3scn" or +".pyscn" file extension and load the script into the embedded python interpreter. Whereas traditional XML-based scene +file would discribe the SOFA scene structure, the python scene script will instead programmatically construct the SOFA +scene. -Try it: ```xml ``` +2. The **SofaPython3 bindings** makes the link between the SOFA API and python. These are compiled (C++) python +modules compatible with the C-Python ABI and therefore directly accessible from any python interpreter, given +that the python version is compatible. Hence, the python interpreter embedded inside the *SofaPython3 plugin* will be able +to load these binding modules. In addition, one could load the binding modules directly inside their own python +interpreter without requiring the load of the plugin. - -- Sofa and SofaRuntime are the python module that can be imported in any python interpreter (python3, ipython, jupyter)[DONE], - -Try it: ```python python3 minimalscene.py``` - -- Access to Sofa simulation within the MathLab python interpreter [WIP-POC]. -- Make a full python GUI application (with UI framework like PySide2, pygame) and render an integrated sofa scene in an opengl context [POC] - - -Global diagram of SofaPython3 ------------------------------ .. figure:: images/SP3_global_arch.png - :alt: How SP3 fits in the SOFA usage pipeline - :align: center + :alt: How SP3 fits in the SOFA usage pipeline + :align: center Content ------- - .. toctree:: :glob: :maxdepth: 1 - menu/Welcome - menu/install + menu/Compilation menu/SofaPlugin menu/SofaModule menu/pythonLibraries menu/CustomModule menu/Contributing - -Contributors ------------- - -- Damien Marchal, Research Engineer CNRS -- Bruno Marques, Research Engineer Inria -- Eve Le Guillou, Enginnering Student - diff --git a/docs/sphinx/source/menu/Compilation.rst b/docs/sphinx/source/menu/Compilation.rst new file mode 100644 index 000000000..3b95ec109 --- /dev/null +++ b/docs/sphinx/source/menu/Compilation.rst @@ -0,0 +1,213 @@ +Compilation +=========== + +The compilation of the SofaPython3 can be done automatically when `building SOFA `__, +or it can be done independently using an already compiled/installed SOFA. The former is called an *in-tree build*, which is, +the compilation of SofaPython3 is included inside the build tree of SOFA. The latter is called an *out-of-tree build*, hence +the compilation of SofaPython3 is done in its own build tree, usually placed somewhere else than SOFA. This page will +cover both methods. + +Prerequisites +------------- +The compilation of SofaPython3 requires the installation of some dependencies. The following table lists all of those +prerequisites. + +.. content-tabs:: + + .. tab-container:: tab1 + :title: Ubuntu + + .. list-table:: + :widths: 15 10 30 45 + :header-rows: 1 + + * - Package + - Type + - Installation + - Description + * - Python 3 libs + - **Required** + - ``sudo apt install python3-dev`` + - Used to link against the C-Python API + * - `pybind11 `__ + - **Required** + - ``sudo apt install pybind11-dev`` + - Heavily used to automatically create the binding code between SOFA and python + * - `SOFA Framework `__ + - **Required** + - You can either `download it `__, or + `compile it `__ from sources + - + + + .. tab-container:: tab2 + :title: MacOS + + .. list-table:: + :widths: 15 10 30 45 + :header-rows: 1 + + * - Package + - Type + - Installation + - Description + * - Python 3 libs + - **Required** + - ``brew install python3`` + - Used to link against the C-Python API + * - `pybind11 `__ + - **Required** + - ``brew install pybind11`` + - Heavily used to automatically create the binding code between SOFA and python + * - `SOFA Framework `__ + - **Required** + - You can either `download it `__, or + `compile it `__ from sources + - + + .. tab-container:: tab3 + :title: Windows + + .. list-table:: + :widths: 15 10 30 45 + :header-rows: 1 + + * - Package + - Type + - Installation + - Description + * - Python 3 libs + - **Required** + - Install the latest Python 3 from `here `__ + - Used to link against the C-Python API + * - `pybind11 `__ + - **Required** + - Compile and install it from `sources `__. Then, add the installation + path to your PATH environment variable. + - Heavily used to automatically create the binding code between SOFA and python + * - `SOFA Framework `__ + - **Required** + - You can either `download it `__, or + `compile it `__ from sources + - + + .. warning:: + + Add the installation path of each of those dependencies into your environment variable. For example, + using the PowerShell of Windows: + + .. code-block:: powershell + + PS $env:Path += ";C:\sofa;C:\pybind11;C:\python" + +In-tree build +------------- + +We use here the term *in-tree build* to indicate that we wish to compile SofaPython3 in the same build tree as SOFA, which is, +compiling SOFA will automatically compile SofaPython3 as an internal subproject. In this case, the compilation of the +plugin should be straightforward, given that you installed correctly all the dependencies of SofaPython3. + +Follow the same steps as the one needed to compile SOFA : ``__. +When you get to the step **Generate a Makefile with CMake**, activate the CMake option **SOFA_FETCH_SOFAPYTHON3**: + +.. figure:: /images/cmake_fetch_sp3.jpg + :alt: Activate the cmake option SOFA_FETCH_SOFAPYTHON3 + :align: center + +and configure CMake. This will pull the source code of SofaPython3 into the `application/plugins` directory of SOFA's +source directory. + +.. note:: + + The CMake option **SOFA_FETCH_SOFAPYTHON3** should disable itself automatically once CMake has been configure one + time. This is to prevent pulling again the SofaPython3 source code again the next time you run cmake. If you need + to update the plugin, you can manually turn the option `ON` again to pull the latest changes made in SofaPython3. + +Once cmake has pulled the source code of SofaPython3 into the `application/plugins` directory, a new CMake option should +now be available : **PLUGIN_SOFAPYTHON3**. Make sure you activate it and re-run CMake configure and generate: + +.. figure:: /images/cmake_activate_sp3.jpg + :alt: Activate the cmake option PLUGIN_SOFAPYTHON3 + :align: center + +If everything went fine during the cmake configuration stage, you should be able to find some information on the version +of python and pybind11 used for the compilation of the plugin: + +.. code-block:: bash + + $ cmake .. + (...) + Adding plugin SofaPython3 + -- Python: + Version: 3.9.1 + Executable: /usr/bin/python3.9 + Headers: /usr/include/python3.9 + Libraries: /usr/lib64/libpython3.9.so + User site: /home/jnbrunet/.local/lib/python3.9/site-packages + -- pybind11: + Version: 2.6.1 + Config: /usr/share/cmake/pybind11/pybind11Config.cmake + (...) + -- Configuring done + -- Generating done + -- Build files have been written to: /home/jnbrunet/sources/sofa/build + +At this point, you are ready to start the compilation of SOFA and the SofaPython3 plugin. + +Out-of-tree build +----------------- + +If you want to compile the SofaPython3 plugin out-of-tree, you will need to either: + +* [**Method 1**] Install the `SOFA binaries and headers `__ + somewhere on your computer and note its installation directory. Or, +* [**Method 2**] Compile it following the `SOFA build documentation `__. + Once it is built, execute the installation by going into the build directory of SOFA (for example, + */home/user/sofa/build/master/*), and using the command ``cmake --install .`` + +.. warning:: + + If you choose the first method (installing the binaries), make sure you have all the SOFA dependencies installed on + your system (e.g. boost, Eigen3, etc.). You can follow the same instructions as if you had chosen the second method + (compiling SOFA), but skipping the compilation part. + +Once done, export the installation path of SOFA inside the ``SOFA_ROOT`` environment variable. For example, + +.. code-block:: bash + + $ export SOFA_ROOT="/home/user/sofa/build/master/install" + + +.. note:: + + To make sure your ``SOFA_ROOT`` is well defined, you can verify that the following file path exists: + + .. code-block:: bash + + $SOFA_ROOT/lib/cmake/SofaFramework/SofaFrameworkTargets.cmake + +We are now ready to compile SofaPython3. Let's first create three new environment variables: **SP3_SRC**, **SP3_BUILD** +and **SP3_ROOT** that will be use to set the location to the source code, the built files and the installed files, +respectively. For example: + +.. code-block:: bash + + $ export SP3_SRC=/opt/SofaPython3/src + $ export SP3_BUILD=/opt/SofaPython3/build + $ export SP3_ROOT=/opt/SofaPython3/build/install + +Let's now pull the source code of the plugin, configure the build and start the compilation and installation. + +.. code-block:: bash + + $ git clone https://github.com/sofa-framework/SofaPython3.git $SP3_SRC + $ cmake -DCMAKE_PREFIX_PATH=$SOFA_ROOT/lib/cmake \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_INSTALL_PREFIX=$SP3_ROOT\ + -S $SP3_SRC \ + -B $SP3_BUILD + $ cmake --build $SP3_BUILD + $ cmake --install $SP3_BUILD + +That's it, you are now ready to use SofaPython3. Keep the environment variable **SOFA_ROOT** and **SP3_ROOT** close by +for the upcoming sections. \ No newline at end of file diff --git a/docs/sphinx/source/menu/install.rst b/docs/sphinx/source/menu/install.rst deleted file mode 100644 index 1e8629f7e..000000000 --- a/docs/sphinx/source/menu/install.rst +++ /dev/null @@ -1,39 +0,0 @@ -Download and Install -================================ - -The plugin can be compiled from the source. - -Install from source -------------------- - -Requirement Install -^^^^^^^^^^^^^^^^^^^ -- have an up to date version of the sofa source code from the master repository -- pybind11 (minimal 2.2.4) -- cmake (minimal 3.12) -- developement package for python3.7 (python3.7-dev) -- numpy - -In-tree build -^^^^^^^^^^^^^^^^^^^ - -If you have already compiled and installed SOFA, you will have to do it again, and add some configuration to CMAKE: - - * Add this directory path in `SOFA_EXTERNAL_DIRECTORIES`. - * Check the `PLUGIN_SOFAPYTHON3` box - * You may need to add an entry called `SofaPython3_DIR`, of the value /cmake - - - -You may also need to add to your variable `PYTHONPATH` the string: /lib/site-packages - - -NB: This plugin cannot be build through in-build process when the old SofaPython plugin is activated. To have both SofaPython3 and SofaPython you need to use out-of-tree build. - -Out-of-tree build -^^^^^^^^^^^^^^^^^^^ - -This plugin should compile with out-of-tree builds. - - -