diff --git a/.gitignore b/.gitignore
index 424d618..eff9447 100644
--- a/.gitignore
+++ b/.gitignore
@@ -68,6 +68,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+doc/_build/
+doc/_autosummary/
 
 # PyBuilder
 target/
diff --git a/doc/conf.py b/doc/conf.py
index 5dd1b91..359bca0 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -19,6 +19,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 # sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration ------------------------------------------------
 
@@ -38,7 +39,10 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.coverage',
     'sphinx.ext.todo',
-    'sphinx.ext.napoleon'
+    'sphinx.ext.napoleon',
+    'sphinx_rtd_theme',
+    "nbsphinx",
+    "myst_parser"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -48,8 +52,11 @@
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+# source_suffix = '.rst'
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -301,4 +308,4 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/', None)}
diff --git a/doc/environment.yml b/doc/environment.yml
index 1ba0ce2..228c224 100644
--- a/doc/environment.yml
+++ b/doc/environment.yml
@@ -7,3 +7,9 @@ dependencies:
   - python
   - sphinx_rtd_theme
   - openalea.phenomenal
+  - ipykernel
+  - ipyvolume
+  - ipython_genutils
+  - pip
+  - pip:
+    - nbsphinx
diff --git a/doc/index.rst b/doc/index.rst
index 37236dc..bb8d4ef 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -2,29 +2,15 @@
 Welcome to openalea.phenomenal's documentation!
 ======================================================
 
-Contents:
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
 
 .. toctree::
+   :hidden:
    :maxdepth: 2
 
-   readme
+   Home <self>
    installation
    usage
    authors
-   
-API reference
-=============
-
-.. toctree::
-   :maxdepth: 2
-
    api
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
-
diff --git a/doc/installation.rst b/doc/installation.rst
index fb6dd9d..3a0bd12 100644
--- a/doc/installation.rst
+++ b/doc/installation.rst
@@ -2,7 +2,53 @@
 Installation
 ============
 
-Download source then, at the command line::
+You must use conda environement : https://docs.conda.io/en/latest/index.html
 
-    $ python setup.py
+Users
+=====
+
+Create a new environment with phenomenal installed in there
+-----------------------------------------------------------
+
+.. code-block:: bash
+
+    mamba create -n phm -c conda-forge -c openalea openalea.phenomenal
+    mamba activate phm
+
+Install phenomenal in a existing environment
+---------------------------------------------
+
+.. code-block:: bash
+
+    mamba install -c conda-forge -c openalea openalea.phenomenal
+
+(Optional) Test your installation
+---------------------------------
+
+.. code-block:: bash
+
+    mamba install -c conda-forge pytest
+    git clone https://github.com/openalea/phenomenal.git
+    cd phenomenal/test; pytest
+
+Developers
+==========
+
+Install From source
+-------------------
+
+.. code-block:: bash
+
+    # Install dependency with conda
+    mamba create -n phm -c conda-forge python
+    mamba activate phm
+    mamba install -c conda-forge -c numba cython numpy numba scipy scikit-image scikit-learn networkx opencv matplotlib vtk pytest skan=0.10
+
+    # Load phenomenal and install
+    git clone https://github.com/openalea/phenomenal.git
+    cd phenomenal
+    python setup.py develop
+
+    # (Optional) Test your installation
+    cd test; pytest
 
diff --git a/doc/readme.rst b/doc/readme.rst
index 8edb73b..bdff72a 100644
--- a/doc/readme.rst
+++ b/doc/readme.rst
@@ -1,24 +1 @@
-=======
-Install
-=======
-
-Download sources and use setup::
-
-    $ python setup.py install
-    or
-    $ python setup.py develop
-
-
-Use
-===
-
-Simple usage:
-
-.. code-block:: python
-
-    from openalea.phenomenal import *
-
-
-
-Acknowledgments
-===============
+.. include:: ../README.md
diff --git a/doc/usage.rst b/doc/usage.rst
index 10e603e..3f744a8 100644
--- a/doc/usage.rst
+++ b/doc/usage.rst
@@ -2,3 +2,14 @@
 Usage
 =====
 
+.. toctree::
+   :maxdepth: 1
+
+   examples/Binarization
+   examples/McCormick_Validation
+   examples/Synthetic_Validation
+   examples/Calibration
+   examples/Multi-view reconstruction and Meshing
+   examples/Tracking
+   examples/Leaf_extension
+   examples/Segmentation
\ No newline at end of file