Improve documentation (#127)

* first

* temp

* second

Signed-off-by: Jean-Nicolas Brunet <[email protected]>

* add images

Co-authored-by: Jean-Nicolas Brunet <[email protected]>

Author: hugtalbot

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

docs/sphinx/source/_templates/layout.html

@@ -0,0 +1,6 @@
+{% extends "!layout.html" %}
+
+{% block menu %}
+<a href="{{ pathto(master_doc) }}">Overview</a>
+{{ super() }}
+{% endblock %}

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, [email protected]'
-author = u'[email protected]'
+copyright = u'2020, SOFA Framework'
+author = u'[email protected]'
 
 # 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.

docs/sphinx/source/images/cmake_activate_sp3.jpg

@@ -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 <https://www.sofa-framework.org>`_.
+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 <RequiredPlugin='SofaPython3'/>```
+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
-