diff --git a/.readthedocs.yml b/.readthedocs.yml index 2306f67..8fd5f15 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,7 +1,7 @@ version: 2 build: - os: "ubuntu-22.04" + os: "ubuntu-24.04" tools: python: "mambaforge-22.9" diff --git a/README.md b/README.md index a3646e0..056fc27 100644 --- a/README.md +++ b/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** : -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 +``` diff --git a/conda/environment.yml b/conda/environment.yml index 2260c2d..ca2b561 100644 --- a/conda/environment.yml +++ b/conda/environment.yml @@ -8,7 +8,6 @@ dependencies: - pip - qtconsole - QtPy - - scipy - openalea.core - openalea.scipack - openalea.oalab diff --git a/doc/_static/ipython.png b/doc/_static/ipython.png index 7ec214a..3deadbb 100644 Binary files a/doc/_static/ipython.png and b/doc/_static/ipython.png differ diff --git a/doc/_static/visualea.png b/doc/_static/visualea.png index c2b6b65..a533bc1 100644 Binary files a/doc/_static/visualea.png and b/doc/_static/visualea.png differ diff --git a/doc/conf.py b/doc/conf.py index 18e2cd5..50c791b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,68 +1,60 @@ # -*- 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. # @@ -70,27 +62,29 @@ # 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)} \ No newline at end of file +intersphinx_mapping = {'python': ('https://docs.python.org/', None)} \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index baeed5b..6e28928 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -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 - Reference Guide - -- 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 `_ - license is a LGPL compatible license. +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` -.. |visualea| replace:: OpenAlea.Visualea diff --git a/doc/user/manual.rst b/doc/user/manual.rst index 66147c6..be594d2 100644 --- a/doc/user/manual.rst +++ b/doc/user/manual.rst @@ -1,28 +1,28 @@ VisuAlea Manual ############### -Visualea is a high level visual programming GUI for OpenAlea +Visualea is a high level visual programming GUI for OpenAlea. -On Linux, in a shell, run the following command:: +On Linux, run the following command in the conda environement - $visualea +.. code-block:: bash -On Windows:: + visualea - Use start→ OpenAlea → Visualea - Main Window +On Windows + +.. code-block:: bash + + visualea.exe -CHANGE THIS PICTURE .. image:: ../_static/visualea.png - :scale: 75 :align: left -The main window is composed of : +The main window is composed of: * The package manager (lists nodes), - * The workspaces where one can graphically assemble dataflows, + * The workspaces where dataflows are graphically assembled, * Each node has it's own graphical interface, * The python interpreter for low level interaction (with code completion) - * Python code editor Package Manager =============== @@ -32,18 +32,18 @@ The package manager finds the available components on the system. :scale: 100 :align: left -It provides different tabs : +It provides different tabs: * The package tab lists packages and nodes in their physical hierarchy. * The category tab sorts nodes into logical categories to ease-up lookup. - * The search tab : search node by matching pattern with node name, category and description. + * The search tab: search node by matching pattern with node name, category and description. Package / Node / Dataflow ------------------------- The package manager contains packages. A package is a distribution unit containing a set of components ( node / graphs). -A package has several associated informations like : +A package has several associated informations like: * Authors * Institutes @@ -54,15 +54,17 @@ A package has several associated informations like : These package informations are accessible from the context menu: * Package Context Menu - o Open Url : Open associated url - o Infos : Display meta informations -Each package element has also a context menu : + - Open Url: Open associated url + - Infos: Display meta informations + +Each package element has also a context menu: * Node (Component) Context Menu - o Open : Open the node - o Edit : Edit the node (Code Editor for Python node, Dataflow for Composite node) - o Remove : Remove the node from the package + + - Open: Open the node + - Edit: Edit the node (Code Editor for Python node, Dataflow for Composite node) + - Remove: Remove the node from the package .. note:: Tooltip are available by moving the mouse pointer on an object. @@ -75,13 +77,15 @@ User packages / system packages Package Manager operations (menu) ================================= - * → Load wralea_file : load a particular package description file - * → Reload all packages : search all packages on the local system - * → Find Nodes : Open the search tab - * → Create - o → Package : Create a new user package - o → Python Node : Create a new component based on python code - o → Composite Node : Create a new component based on other components (Macro node) + * → Load package/directory: load a particular package description file + * → Reload all packages: search all packages on the local system + * → Find Nodes: Open the search tab + * → Add + + - → Package: Create a new user package + - → Composite Node: Create a new component based on other components (Macro node) + - → Python Node: Create a new component based on python code + - → Data File: Create a new data file Workspaces ---------- @@ -91,15 +95,15 @@ User can create simple process by interconnecting boxes together. A box represen Opening workspaces ================== -You can create several workspaces : +You can create several workspaces: - * Workspace → New empty workspace or CTRL + W + * Workspace → New empty workspace or CTRL + T * Double click on a graph in the package manager. In this case the workspace contains the graph. Adding new nodes ================ -* You can add nodes by doing a drag and drop between the package manager and the workspace. -* You also do Copy/Paste operation directly in the workspace. +* You can add nodes by drag and drop between the package manager and the workspace. +* You can also do Copy/Paste operation directly in the workspace. A node is represented by a box with input and outputs ports. @@ -119,13 +123,14 @@ You can connect the nodes between them by doing a drag and drop operation betwee :height: 200px :scale: 100 -* An output port can be connected to several different input ports : in this case the value will be copied to the different port -* An input port can be connected to several different output ports : in this cas the value will be the list of the different value of the connected output ports. +* An output port can be connected to several different input ports: in this case the value will be copied to the different port +* An input port can be connected to several different output ports: in this cas the value will be the list of the different value of the connected output ports. Node Graphical interface ======================== -Each node has a configuration dialog (its widget). You can open the widget with the context menu (right click → open widget). +Each node has a configuration dialog (its widget). You can open the widget with the context menu (right click → open widget) +or by double clicking the node. The widget depends of the node, it can be a simple value editor (spinbox for numbers, text editor…), or complex editor like 3D visualizer. @@ -134,33 +139,34 @@ Running a dataflow The graph of nodes form an expression. -To evaluate the expression : +To evaluate the expression: * Menu → Workspace → Run will evaluate all the graph - * Context Menu → Run on a particular node will evaluate only the selected node and its dependencies. + * Context Menu → Run on a particular node will evaluate only the selected node and its parents. -If you change a value of a node, the evaluation algorithm will compute only the changed nodes and their dependencies, avoiding to do several times the same computation. +If you change a value of a node, the evaluation algorithm will compute only the changed nodes and their dependencies, +avoiding to do several times the same computation. .. deprecated:: The node contained in a graph can be in different states/ The color of a node depends of its state: - * Red : the node need to be reevaluated - * Blue : the node doesn't need to be reevaluated + * Red: the node need to be reevaluated + * Blue: the node doesn't need to be reevaluated To change the status of a node or of a dataflow: * Context Menu → Reset: Reset the corresponding node - * Workspace → Reset : Reset all the dataflow - * Workspace → Invalidate : Force all nodes to be reevaluated the next time + * Workspace → Reset: Reset all the dataflow + * Workspace → Invalidate: Force all nodes to be reevaluated the next time -You can visualize the value of a port : Context Menu → Print and with tooltips. +You can visualize the value of a port: Context Menu → Print and with tooltips. Save a dataflow / Composite Node ================================ A Composite node is an abstraction of a dataflow graph. It is a node which contains other nodes. -Composite nodes are used to : +Composite nodes are used to: * save a dataflow * manage complexity @@ -168,16 +174,16 @@ Composite nodes are used to : Saving a dataflow ----------------- -To save a dataflow : +To save a dataflow: - * Save the workspace as a composite node : Workspace → Save as composite node or CTRL + E + * Save the workspace as a composite node: Workspace → Save as composite node or CTRL + E This function will save the graph but also the value of the node inputs Managing complexity ------------------- -A composite node can be reused as a normal node (a simple box). You can embed a part of a graph in a composite node : +A composite node can be reused as a normal node (a simple box). You can embed a part of a graph in a composite node: * Select the node you want to group/embed * Workspace → Group or CTRL +G @@ -188,17 +194,17 @@ This function can be used to improve the readability of your graph and facilitat I/O --- -As normal node, a composite node has inputs and outputs. They can be set : +As normal node, a composite node has inputs and outputs. They can be set: * Workspace → configure I/O -Each input has : +Each input has: * a name * an interface (used for the graphical interface and for type checking) * a default value -Each output has : +Each output has: * a name * an interface (used for type checking) @@ -208,25 +214,25 @@ Open/Save a session You can save the entire session in order to keep all the data you currently use. - * File → save session : Save the current session for a furur reuse - * File → open session : Open a previously saved session - * File → new session : reinitialize all the workspace + * File → save session: Save the current session for a furur reuse + * File → open session: Open a previously saved session + * File → new session: reinitialize all the workspace .. warning:: This functionality is not safe and we do NOT recommand to use it. Use export as composite node instead to save your work Export Application ================== -A graph can be exported as a standalone application (a python module) : Workspace → Export to Application. +A graph can be exported as a standalone application (a python module): Workspace → Export to Application. -The application can be previewed with the command : Workspace → Preview Application. +The application can be previewed with the command: Workspace → Preview Application. Data Pool --------- The data pool is a kind of data clipboard to store temporally computed data. - * You can send data to the Pool : Port Context menu → Send to pool + * You can send data to the Pool: Port Context menu → Send to pool * You can re-use data of the pool in the dataflow by doing a drag and drop from the datapool list to aaninput port. * You can also access to the datapool in the interpreter (drag and drop to the interpreter will copy the correct code): @@ -238,13 +244,12 @@ Python Operations At any moment, you can use the python interpreter to launch python command or scripts. -CHANGE THIS PICTURE .. image:: ../_static/ipython.png - :width: 80% - :height: 200px - :scale: 100 + :width: 100% + :height: 200px + :scale: 100 -The interpreter defines special variables : +The interpreter defines special variables: * session contains the different workspaces and the nodes they contain * datapool is the datapool dictionary @@ -257,21 +262,4 @@ You can also do a drag and drop from the datapool. Preferences ----------- -Interface preferences can be set via the preference dialog : Window → Preferences - -Package manager -=============== - -This tab is used to set the directories to search for openalea packages. - -.. warning:: section to be filled - -Dataflow Python editor -====================== - -.. warning:: section to be filled - -UI -== - -.. warning:: section to be filled +Interface preferences can be set via the preference dialog: Window → Preferences diff --git a/pyproject.toml b/pyproject.toml index e7d0870..99533c2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -73,9 +73,12 @@ doc = [ "myst-parser", "nbsphinx", "sphinx-copybutton", + "ipykernel", + "ipython_genutils", ] [project.urls] +Repository = "https://github.com/openalea/visualea" Homepage = "https://visualea.rtfd.io/" "Bug Tracker" = "https://github.com/openalea/visualea/issues" Discussions = "https://github.com/openalea/visualea/discussions"