Update documentation

Author: PierreRaybaut

en/.doctrees/contributing/changelog.doctree

@@ -24,12 +24,17 @@ What is a plugin?
 A plugin is a Python module that is loaded at startup by DataLab. A plugin may
 add new features to DataLab, or modify existing features.
 
-A plugin is a Python module that contains a class derived from the
-:class:`cdl.plugins.PluginBase` class. The name of the class is not important,
-as long as it is derived from :class:`cdl.plugins.PluginBase` and has a
-``PLUGIN_INFO`` attribute that is an instance of the :class:`cdl.plugins.PluginInfo`
-class. The ``PLUGIN_INFO`` attribute is used by DataLab to retrieve information
-about the plugin.
+A plugin is a Python module which file name starts with ``cdl_``, and which
+contains a class derived from the :class:`cdl.plugins.PluginBase` class.
+The name of the class is not important, as long as it is derived from
+:class:`cdl.plugins.PluginBase` and has a ``PLUGIN_INFO`` attribute that is an
+instance of the :class:`cdl.plugins.PluginInfo` class. The ``PLUGIN_INFO`` attribute
+is used by DataLab to retrieve information about the plugin.
+
+.. note::
+
+    DataLab's plugin discovery mechanism will only load plugins that are defined
+    in Python files which names start with ``cdl_`` (e.g. ``cdl_myplugin.py``).
 
 Where to put a plugin?
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -49,6 +54,34 @@ Special additional locations are available for plugins:
 - The `plugins` directory in the `cdl` package in case for internal plugins
   only (i.e. it is not recommended to put your own plugins there).
 
+How to develop a plugin?
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+To develop a plugin, you may start by deriving from one of the example plugins
+(see below) and modify it to suit your needs.
+
+If you want to code a plugin in your usual Python development environment (preferably
+with an IDE like `Spyder <https://www.spyder-ide.org/>`_) and take advantage of the
+code completion, you can add the `cdl` package to your Python path.
+
+This can be done:
+
+- By installing DataLab in your Python environment (using one of the following methods:
+  :ref:`install_pip`, :ref:`install_wheel`, or :ref:`install_source`),
+
+- Or by adding the `cdl` package to your Python path manually:
+
+  - Download the DataLab source code from the `PyPI page <https://pypi.org/project/cdl/>`_,
+  - Unzip the source code to a folder on your computer,
+  - Add the `cdl` package to your Python path (e.g. by using the *PYTHONPATH Manager* in Spyder).
+
+.. note::
+
+    Even if you have installed the `cdl` package properly in your Python environment,
+    you won't be able to run the DataLab application from your development environment
+    to test your plugin. You will need to run DataLab from the command line or from
+    the shortcut created during the installation.
+
 Example: processing plugin
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 

en/.doctrees/environment.pickle

@@ -520,12 +520,17 @@
 <h2>What is a plugin?<a class="headerlink" href="#what-is-a-plugin" title="Link to this heading">#</a></h2>
 <p>A plugin is a Python module that is loaded at startup by DataLab. A plugin may
 add new features to DataLab, or modify existing features.</p>
-<p>A plugin is a Python module that contains a class derived from the
-<a class="reference internal" href="#cdl.plugins.PluginBase" title="cdl.plugins.PluginBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">cdl.plugins.PluginBase</span></code></a> class. The name of the class is not important,
-as long as it is derived from <a class="reference internal" href="#cdl.plugins.PluginBase" title="cdl.plugins.PluginBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">cdl.plugins.PluginBase</span></code></a> and has a
-<code class="docutils literal notranslate"><span class="pre">PLUGIN_INFO</span></code> attribute that is an instance of the <a class="reference internal" href="#cdl.plugins.PluginInfo" title="cdl.plugins.PluginInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">cdl.plugins.PluginInfo</span></code></a>
-class. The <code class="docutils literal notranslate"><span class="pre">PLUGIN_INFO</span></code> attribute is used by DataLab to retrieve information
-about the plugin.</p>
+<p>A plugin is a Python module which file name starts with <code class="docutils literal notranslate"><span class="pre">cdl_</span></code>, and which
+contains a class derived from the <a class="reference internal" href="#cdl.plugins.PluginBase" title="cdl.plugins.PluginBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">cdl.plugins.PluginBase</span></code></a> class.
+The name of the class is not important, as long as it is derived from
+<a class="reference internal" href="#cdl.plugins.PluginBase" title="cdl.plugins.PluginBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">cdl.plugins.PluginBase</span></code></a> and has a <code class="docutils literal notranslate"><span class="pre">PLUGIN_INFO</span></code> attribute that is an
+instance of the <a class="reference internal" href="#cdl.plugins.PluginInfo" title="cdl.plugins.PluginInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">cdl.plugins.PluginInfo</span></code></a> class. The <code class="docutils literal notranslate"><span class="pre">PLUGIN_INFO</span></code> attribute
+is used by DataLab to retrieve information about the plugin.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>DataLab’s plugin discovery mechanism will only load plugins that are defined
+in Python files which names start with <code class="docutils literal notranslate"><span class="pre">cdl_</span></code> (e.g. <code class="docutils literal notranslate"><span class="pre">cdl_myplugin.py</span></code>).</p>
+</div>
 </section>
 <section id="where-to-put-a-plugin">
 <h2>Where to put a plugin?<a class="headerlink" href="#where-to-put-a-plugin" title="Link to this heading">#</a></h2>
@@ -542,6 +547,33 @@ <h2>Where to put a plugin?<a class="headerlink" href="#where-to-put-a-plugin" ti
 only (i.e. it is not recommended to put your own plugins there).</p></li>
 </ul>
 </section>
+<section id="how-to-develop-a-plugin">
+<h2>How to develop a plugin?<a class="headerlink" href="#how-to-develop-a-plugin" title="Link to this heading">#</a></h2>
+<p>To develop a plugin, you may start by deriving from one of the example plugins
+(see below) and modify it to suit your needs.</p>
+<p>If you want to code a plugin in your usual Python development environment (preferably
+with an IDE like <a class="reference external" href="https://www.spyder-ide.org/">Spyder</a>) and take advantage of the
+code completion, you can add the <cite>cdl</cite> package to your Python path.</p>
+<p>This can be done:</p>
+<ul class="simple">
+<li><p>By installing DataLab in your Python environment (using one of the following methods:
+<a class="reference internal" href="../../intro/installation.html#install-pip"><span class="std std-ref">Package manager pip</span></a>, <a class="reference internal" href="../../intro/installation.html#install-wheel"><span class="std std-ref">Wheel package</span></a>, or <a class="reference internal" href="../../intro/installation.html#install-source"><span class="std std-ref">Source package</span></a>),</p></li>
+<li><p>Or by adding the <cite>cdl</cite> package to your Python path manually:</p>
+<ul>
+<li><p>Download the DataLab source code from the <a class="reference external" href="https://pypi.org/project/cdl/">PyPI page</a>,</p></li>
+<li><p>Unzip the source code to a folder on your computer,</p></li>
+<li><p>Add the <cite>cdl</cite> package to your Python path (e.g. by using the <em>PYTHONPATH Manager</em> in Spyder).</p></li>
+</ul>
+</li>
+</ul>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>Even if you have installed the <cite>cdl</cite> package properly in your Python environment,
+you won’t be able to run the DataLab application from your development environment
+to test your plugin. You will need to run DataLab from the command line or from
+the shortcut created during the installation.</p>
+</div>
+</section>
 <section id="example-processing-plugin">
 <h2>Example: processing plugin<a class="headerlink" href="#example-processing-plugin" title="Link to this heading">#</a></h2>
 <p>Here is a simple example of a plugin that adds a new features to DataLab.</p>
@@ -1187,6 +1219,7 @@ <h3>DataLab plugin system<a class="headerlink" href="#datalab-plugin-system" tit
     <ul class="visible nav section-nav flex-column">
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#what-is-a-plugin">What is a plugin?</a></li>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#where-to-put-a-plugin">Where to put a plugin?</a></li>
+<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#how-to-develop-a-plugin">How to develop a plugin?</a></li>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#example-processing-plugin">Example: processing plugin</a></li>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#example-input-output-plugin">Example: input/output plugin</a></li>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#other-examples">Other examples</a></li>

en/.doctrees/features/general/plugins.doctree

@@ -560,6 +560,7 @@ <h2>General features<a class="headerlink" href="#general-features" title="Link t
 <li class="toctree-l1"><a class="reference internal" href="general/plugins.html">Plugins</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="general/plugins.html#what-is-a-plugin">What is a plugin?</a></li>
 <li class="toctree-l2"><a class="reference internal" href="general/plugins.html#where-to-put-a-plugin">Where to put a plugin?</a></li>
+<li class="toctree-l2"><a class="reference internal" href="general/plugins.html#how-to-develop-a-plugin">How to develop a plugin?</a></li>
 <li class="toctree-l2"><a class="reference internal" href="general/plugins.html#example-processing-plugin">Example: processing plugin</a></li>
 <li class="toctree-l2"><a class="reference internal" href="general/plugins.html#example-input-output-plugin">Example: input/output plugin</a></li>
 <li class="toctree-l2"><a class="reference internal" href="general/plugins.html#other-examples">Other examples</a></li>