Merge pull request #58 from openalea/doc

Updating doc

Author: baugetfa

.readthedocs.yml

@@ -1,7 +1,7 @@
 version: 2
 
 build:
-  os: "ubuntu-22.04"
+  os: "ubuntu-24.04"
   tools:
     python: "mambaforge-22.9"
 

README.md

@@ -1,33 +1,60 @@
-# OpenAlea.Visualea
+# Visualea
+[![Docs](https://readthedocs.org/projects/visualea/badge/?version=latest)](https://visualea.readthedocs.io/)
+[![Build Status](https://github.com/openalea/visualea/actions/workflows/conda-package-build.yml/badge.svg?branch=master)](https://github.com/openalea/visualea/actions/workflows/conda-package-build.yml?query=branch%3Amaster)
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/License--CeCILL-C-blue)](https://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html)
+[![Anaconda-Server Badge](https://anaconda.org/openalea3/visualea/badges/version.svg)](https://anaconda.org/openalea3/visualea)
 
-OpenAlea.Visualea is the Visual Programming Environment of OpenAlea. It allows using OpenAlea packages 
-without programming language knowledge and to build dataflow graphically.
+![visualea main window](https://github.com/openalea/visualea/blob/master/doc/_static/visualea.png?raw=true "visualea main window")
+
+## Software
+
+### Authors
+
+> -   Christophe Pradal
+
+### Institutes
+
+CIRAD / INRAE / inria
+
+### Status
+
+Python package
 
+### License
 
-## License
+CecILL-C
 
-OpenAlea.Visualea is released under a Cecill v2 license.
+**URL** : <https://visualea.rtfd.io>
 
-See LICENSE.txt
-Nota : Cecill v2 license is a GPL compatible license.
+## About
 
-## Installation user mode
+OpenAlea.Visualea is the Visual Programming Environment of OpenAlea. It allows using OpenAlea packages 
+without programming language knowledge and to build dataflow graphically.
+
+## Installation 
+
+### user mode
 
 ```bash
 mamba create -n visualea -c openalea3 -c conda-forge openalea.visualea
 mamba activate visualea
 ```
 
-## Installation dev mode
+### for developer, in an existing environment
 
-- Clone the repository
-- Use the following command
-    
 ```bash
-mamba create -f conda/environment.yml 
-mamba activate visualea
+git clone 'https://github.com/openalea/visualea.git'
+cd visualea
+mamba install --only-deps -c openalea3 -c conda-forge openalea.visualea
+pip install -e .[options]
 ```
+`[options]` is optional, and allows to install additional dependencies 
+defined in the `[project.optional-dependencies]` section of your 
+pyproject.toml file (usually "dev", or "doc", ...)
 
-The first command will create the *visualea* environment with the dependencies and install 
-**openalea.visualea** in it with     `pip install . -e`. The second will activate the environment.
-
+### for developer, in a new clean isolated environment
+```bash
+mamba env create -f conda/environment.yml 
+mamba activate visualea
+```

conda/environment.yml

@@ -8,7 +8,6 @@ dependencies:
   - pip
   - qtconsole
   - QtPy
-  - scipy
   - openalea.core
   - openalea.scipack
   - openalea.oalab

doc/_static/ipython.png

@@ -1,96 +1,90 @@
 # -*- coding: utf-8 -*-
-import os
 import sys
-from importlib.metadata import metadata
+import os
+
+import pydata_sphinx_theme # Pydata theme: https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html
 
-pkg_name='visualea'
-meta = metadata('openalea.' + pkg_name)
+from importlib.metadata import metadata
+project='visualea'
+meta = metadata('openalea.' + project)
 release = meta.get("version")
 # for example take major/minor
 version = ".".join(release.split('.')[:3])
-author = meta['Author'].split(',')[0] + "et al."
+author = meta['Author'].split(' <')[0]
 desc = meta['Summary']
+urls = {k:v for k,v in [item.split(',') for item in meta.get_all('Project-URL')]}
+
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # 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(".."))  # to include the root of the package
+sys.path.insert(0, os.path.abspath('..')) # to include the root of the package
 
 # -- General configuration ------------------------------------------------
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx.ext.autodoc",  # support for automatic inclusion of docstring
-    "sphinx.ext.autosummary",  # generates autodoc summaries
-    "sphinx.ext.doctest",  # inclusion and testing of doctest code snippets
-    "sphinx.ext.intersphinx",  # support for linking to other projects
-    "sphinx.ext.imgmath",  # support for math equations
-    "sphinx.ext.ifconfig",  # support for conditional content
-    "sphinx.ext.viewcode",  # support for links to source code
-    "sphinx.ext.coverage",  # includes doc coverage stats in the documentation
-    "sphinx.ext.todo",  # support for todo items
-    "sphinx.ext.napoleon",  # support for numpy and google style docstrings
-    "sphinx_favicon",  # support for favicon
-    "nbsphinx",  # for integrating jupyter notebooks
-    "myst_parser",  # for parsing .md files
+    'sphinx.ext.autodoc',  # support for automatic inclusion of docstring
+    'sphinx.ext.autosummary',  # generates autodoc summaries
+    'sphinx.ext.doctest',  # inclusion and testing of doctest code snippets
+    'sphinx.ext.intersphinx', # support for linking to other projects
+    'sphinx.ext.mathjax',  # support for math equations
+    'sphinx.ext.ifconfig',  # support for conditional content
+    'sphinx.ext.viewcode',  # support for links to source code
+    'sphinx.ext.coverage',  # includes doc coverage stats in the documentation
+    'sphinx.ext.todo',      # support for todo items
+    'sphinx.ext.napoleon',  # support for numpy and google style docstrings
+    "sphinx_favicon",      # support for favicon
+    "sphinx_copybutton",      # support for copybutton in code blocks
+    "nbsphinx",     # for integrating jupyter notebooks
+    "myst_parser"   # for parsing .md files
 ]
-
-
-nbsphinx_thumbnails = {
-    'examples/Segmentation': '_static/segmentation_thumb.png',
-}
-
-nbsphinx_allow_errors = True
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+templates_path = ['_templates']
 autosummary_generate = True
-exclude_patterns = ["_build", "_templates"]
+exclude_patterns = ['build', '_build', '_templates']
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 source_suffix = {
-    ".rst": "restructuredtext",
-    ".md": "markdown",
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
 }
 # The master toctree document.
-master_doc = "index"
+master_doc = 'index'
 # General information about the project.
-project = pkg_name
-copyright = "Cecill-C INRAE / INRIA / CIRAD"
-author = author
-# 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.
-#
+copyright = u'Cecill-C INRAE / INRIA / CIRAD'
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
 language = "en"
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
+pygments_style = 'sphinx'
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
 # -- Options for HTML output ----------------------------------------------
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "pydata_sphinx_theme"
+html_theme = 'pydata_sphinx_theme'
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-    "header_links_before_dropdown": 6,
-    "sidebarwidth": 200,
-    "collapse_navigation": "false",
-    "icon_links": [
-        {
-            "name": "GitHub",
-            "url": "https://github.com/openalea/visualea",
-            "icon": "fa-brands fa-github",
-        },
+  "header_links_before_dropdown": 6,
+  "sidebarwidth": 200,
+  "sticky_navigation": "false",
+  "collapse_navigation": "false",
+  "display_version": "true",
+  "icon_links": [
+    {
+        "name": "GitHub",
+        "url": "https://github.com/openalea/visualea", # do not want urls['Repository']
+        "icon": "fa-brands fa-github",
+    },
     ],
     "show_version_warning_banner": True,
     "footer_start": ["copyright"],
@@ -99,11 +93,12 @@
         "**/*": ["page-toc", "edit-this-page", "sourcelink"],
         "examples/no-sidebar": [],
     },
-}
+    "use_edit_page_button": True,
+  }
 # 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 = ['_static']
 html_logo = "_static/openalea_web.svg"
 html_favicon = "_static/openalea_web.svg"
 # If false, no module index is generated.
@@ -119,48 +114,40 @@
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
 html_show_copyright = True
 # Output file base name for HTML help builder.
-htmlhelp_basename = "visualea_documentation"
-
+htmlhelp_basename = project + '_documentation'
 # Add infomation about github repository
 html_context = {
     # "github_url": "https://github.com", # or your GitHub Enterprise site
     "github_user": "openalea",
     "github_repo": "visualea",
-    "github_version": "main",
+    "github_version": "master",
     "doc_path": "doc",
 }
 
 # -- Options for LaTeX output ---------------------------------------------
-latex_elements = {}
+latex_elements = {
+}
 latex_documents = [
-    (
-        master_doc,
-        "visualea.tex",
-        "visualea Documentation",
-        "INRA / INRIA / CIRAD",
-        "manual",
-    ),
+    (master_doc, 'visualea.tex', u'visualea Documentation',
+     u'INRA / INRIA / CIRAD', 'manual'),
 ]
 
 # -- Options for manual page output ---------------------------------------
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "openalea.visualea", "visualea Documentation", [author], 1)]
+man_pages = [
+    (master_doc, project, project + ' Documentation',
+     [author], 1)
+]
 
 # -- Options for Texinfo output -------------------------------------------
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (
-        master_doc,
-        "visualea",
-        "visualea Documentation",
-        author,
-        "visualea",
-        "this is an example",
-        "Miscellaneous",
-    ),
+    (master_doc, project, project + ' Documentation',
+     author, project, desc,
+     'Miscellaneous'),
 ]
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"python": ("https://docs.python.org/", None)}
+intersphinx_mapping = {'python': ('https://docs.python.org/', None)}

doc/_static/visualea.png

@@ -1,49 +1,36 @@
-OpenAlea Visualea documentation
-###############################
+Welcome to Visualea's documentation!
+=====================================
 
-Module description
-==================
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
 
-.. sidebar:: Summary
+Contact & Contributing
+----------------------
 
-    :Version: |version|
-    :Release: |release|
-    :Date: |today|
-    :Author: See `Authors`_ section
-    :ChangeLog: See `ChangeLog`_ section
+For any question, please submit to https://github.com/openalea/visualea/issues.
 
-.. topic:: Overview
 
-    .. include:: user/overview.txt
+Versioning
+----------
+
+Sources are versioned on an Git repository hosted by platform GitHub: https://github.com/openalea/visualea.
+If you want to make your own development of the model, please fork the repository.
 
 Documentation
-=============
+-------------
 
 .. toctree::
     :maxdepth: 1
+    :caption: Contents:
 
-    User Guide<user/index.rst>   
-    Reference Guide<user/autosum.rst>
-
-- A `PDF <../latex/main.pdf>`_ version of |visualea| documentation is 
-  available.
-
-Authors
-=======
-
-.. include:: ../AUTHORS.txt
-
-ChangeLog
-=========
-
-.. include:: ../ChangeLog.txt
+    user/manual.rst
+    user/autosum.rst
 
-License
-=======
 
-|visualea| is released under a Cecill-C License.
+Indices and tables
+------------------
 
-.. note:: `Cecill-C <http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html>`_ 
-    license is a LGPL compatible license.
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
 
-.. |visualea| replace:: OpenAlea.Visualea