Better documentation including notebooks and updated stuff (e.g. READ…

…ME welcome page) !

.gitignore

@@ -68,6 +68,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+doc/_build/
+doc/_autosummary/
 
 # PyBuilder
 target/

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

doc/environment.yml

@@ -7,3 +7,9 @@ dependencies:
   - python
   - sphinx_rtd_theme
   - openalea.phenomenal
+  - ipykernel
+  - ipyvolume
+  - ipython_genutils
+  - pip
+  - pip:
+    - nbsphinx

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`
-
-

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
 

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

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