Merge pull request #86 from LaboratoireMecaniqueLille/release/2.0.2

Release of version 2.0.2

CODEOWNERS

@@ -3,3 +3,9 @@
 
 # PIERROOOTT owns the Gstreamer cameras
 /src/crappy/camera/gstreamer_* @WeisLeDocto @PIERROOOTT
+
+# PIERROOOTT owns the Opencv cameras
+/src/crappy/camera/opencv_* @WeisLeDocto @PIERROOOTT
+
+# PIERROOOTT owns the base v4l2 class
+/src/crappy/camera/_v4l2_base.py @WeisLeDocto @PIERROOOTT

docs/source/api.rst

@@ -2,6 +2,8 @@
 API
 ===
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 This section contains the inline documentation of all the objects of the module
 Crappy. In particular, a description is given for each possible argument of the
 classes and methods. The only way to get an even finer understanding of an

docs/source/citing.rst

@@ -2,6 +2,8 @@
 Citing Crappy
 ==============
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 If Crappy has been of help in your research, please reference it in your 
 academic publications by citing one or both of the following articles :
 

docs/source/conf.py

@@ -16,12 +16,12 @@
 from time import gmtime, strftime
 from re import match
 
-__version__ = '2.0.1'
+__version__ = '2.0.2'
 
 # -- Project information -----------------------------------------------------
 
 project = 'Crappy'
-author = 'Antoine Weisrock'
+author = 'LaMcube and contributors'
 copyright = f"{strftime('%Y', gmtime())}, {author}"
 version = match(r'\d+\.\d+', __version__).group()
 release = __version__
@@ -37,7 +37,7 @@
 # Including undocumented features
 autodoc_default_options = {'undoc-members': True}
 # The codeauthor and sectionauthor directives do produce output
-show_authors = True
+show_authors = False
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -52,7 +52,9 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.duration',
     'sphinx_copybutton',
-    'sphinx_tabs.tabs'
+    'sphinx_tabs.tabs',
+    'sphinx_toolbox.collapse',
+    'sphinx_toolbox.changeset'
 ]
 
 # Tabs settings
@@ -232,4 +234,8 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+intersphinx_mapping = {
+  'python': ('https://docs.python.org/3', None),
+  'numpy': ('https://numpy.org/doc/stable/', None),
+  'matplotlib': ('https://matplotlib.org/stable/', None),
+  'psutil': ('https://psutil.readthedocs.io/en/latest/',  None)}

docs/source/developers.rst

@@ -9,6 +9,8 @@ Developers information
 Contributing to Crappy
 ----------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 If you want to help developing Crappy with us, we'll be more than happy to
 welcome you in the community ! Here you'll find some practical information on
 **how Crappy works under the hood, and a few guidelines for contributors**.
@@ -40,6 +42,8 @@ directly committed to.
 Technical description of Crappy
 -------------------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 .. note::
   This is a very simplified overview of how the module actually works. Only the
   main ideas are presented, and many technical aspects are omitted. Reading the
@@ -248,6 +252,8 @@ the examples.
 Detailed runtime sequence of Crappy
 -----------------------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 Crappy's main strength lies in the use of massive parallelization to maximize
 the performance of the module. Unfortunately, this means we had to cope with
 Python's notoriously complex :mod:`multiprocessing` architecture, and come up
@@ -406,7 +412,8 @@ cases :
 
 - If all the Blocks are not done running at the end of this phase.
 - If an :exc:`Exception` was caught during Crappy's execution.
-- If Crappy was stopped using CTRL+C, resulting in a :exc:`KeyboardInterrupt`.
+- If Crappy was stopped using :kbd:`Control-c`, resulting in a
+  :exc:`KeyboardInterrupt`.
 
 The goal of this exception is to stop the execution of the ``__main__``
 Process, to avoid any more code to be executed in case something went wrong in

docs/source/features.rst

@@ -2,6 +2,8 @@
 Current functionalities
 =======================
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 On this page are listed all the objects currently distributed with Crappy and
 exposed to the users. Information on how to use them can be found in the
 :ref:`Tutorials`, as well as guidelines for creating your own objects. For most
@@ -14,6 +16,8 @@ in the :ref:`API`.
 Functionalities (Blocks)
 ------------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 The Blocks are the base bricks of Crappy, that fulfill various functions. In
 the tutorials, you can learn more about :ref:`how to use Blocks
 <1. Understanding Crappy's syntax>` and :ref:`how to create new Blocks
@@ -49,8 +53,8 @@ Data display
   persistent and allows to visualize the history of a label.
 
   The examples folder on GitHub contains `one example of the Grapher Block
-  <https://github.com/LaboratoireMecaniqueLille/crappy/examples/blocks/
-  dashboard.py>`_ specifically, but it is also used in most of the other
+  <https://github.com/LaboratoireMecaniqueLille/crappy/blob/master/examples/
+  blocks/dashboard.py>`_ specifically, but it is also used in most of the other
   examples.
 
   :ref:`A tutorial section <2.c. The Grapher Block>` is also dedicated to the
@@ -366,6 +370,8 @@ Others
 Supported hardware (Cameras, InOuts, Actuators)
 -----------------------------------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 Supported Cameras
 +++++++++++++++++
 
@@ -810,6 +816,8 @@ LaMcube-specific hardware
 On-the-fly data modification (Modifiers)
 ----------------------------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 - :ref:`Demux`
 
   Takes the signal returned by a streaming :ref:`IOBlock` and transforms it

docs/source/index.rst

@@ -2,6 +2,8 @@
 Crappy
 ======
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 Crappy is a **Python module** that aims to provide easy-to-use and open-source
 tools for **command and data acquisition on complex experimental setups**. It
 is designed to let users drive most setups in **less than 100 lines of code**.

docs/source/installation.rst

@@ -9,6 +9,8 @@ Installation
 Requirements
 ------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 Crappy was successfully installed and tested on **Linux** (Ubuntu 18.04 and
 higher), **Windows** (8 and higher) and **MacOS** (Sierra and higher). It was
 also successfully installed on **Raspberry Pi** 3B+ and 4B. As a Python module,
@@ -45,6 +47,8 @@ functionalities (this list is not exhaustive) :
 1. Check your Python version
 ----------------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 Before installing Crappy, first check that you have **a compatible version of**
 **Python** installed. You can get the current version of Python by running
 :shell:`python --version` in a console. The version should then be displayed,
@@ -67,6 +71,8 @@ are beyond the scope of this documentation.
 2. Deploy a virtual environment (optional)
 ------------------------------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 It is **recommended** to install Crappy in a `virtual environment
 <https://docs.python.org/3/library/venv.html>`_, to avoid conflicts with other
 Python packages installed at the user or system level. This step is however not
@@ -85,6 +91,8 @@ console, containing an independent install of Python.
 3. Install Crappy
 -----------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 Once you have a compatible version of Python installed, and after optionally
 setting up a virtual environment, you're **ready to install Crappy**. A single
 line of code is necessary to install Crappy :
@@ -143,6 +151,8 @@ you would need to use along with Crappy. For example :
 4. Check your install
 ---------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 Once you have installed Crappy, you can **run a few checks** to make sure it
 works fine on your system. First, try to simply import it :
 

docs/source/requirements.txt

@@ -1,4 +1,5 @@
 numpy==1.24.3
 sphinx_copybutton==0.5.2
 sphinx-tabs==3.4.1
-sphinx-rtd-theme==1.3.0
+sphinx-rtd-theme==1.3.0
+sphinx-toolbox==3.5.0

docs/source/troubleshooting.rst

@@ -2,6 +2,8 @@
 Troubleshooting
 ===============
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 When encountering a problem with Crappy, please **first carefully read the**
 **present documentation**. Most of the difficulties users may face come from an
 incorrect use of Crappy. If you cannot find an answer in the documentation, you

docs/source/tutorials/complex_custom_objects.rst

@@ -2,6 +2,8 @@
 More about custom objects in Crappy
 ===================================
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 .. role:: py(code)
   :language: python
   :class: highlight
@@ -15,6 +17,8 @@ understanding of the module, or users with a specific need.
 1. Custom Generator Paths
 -------------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 Starting from version 2.0.0, **it is now possible for users to create their**
 **own** :ref:`Generator Paths` ! There are two reasons why this possibility was
 added so late in the module. First, we're not certain that there is a need for
@@ -92,13 +96,17 @@ clearer how to create a custom Generator Path and how to handle the
 conditions. This example generates a square wave, whose duty cycle can be
 either fixed or controlled by the value of an input label :
 
-.. literalinclude:: /downloads/complex_custom_objects/custom_path.py
-   :language: python
-   :emphasize-lines: 35, 40-41, 49, 52-53
+.. collapse:: (Expand to see the full code)
+
+   .. literalinclude:: /downloads/complex_custom_objects/custom_path.py
+      :language: python
+      :emphasize-lines: 35, 40-41, 49, 52-53
+
+|
 
 .. Note::
-   To run this example, you'll need to have the *matplotlib* and *scipy* Python
-   modules installed.
+   To run this example, you'll need to have the :mod:`matplotlib` and *scipy*
+   Python modules installed.
 
 This example contains all the ingredients described above. The parent class is
 initialized, then the :py:`condition` argument is parsed with
@@ -143,6 +151,8 @@ labels).
 2. More about custom InOuts
 ---------------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 In addition to what was described in the tutorial section about :ref:`how to
 create custom InOut objects <3. Custom InOuts>`, there is one more minor
 feature that the :ref:`In / Out` possess and that is worth describing in the
@@ -159,7 +169,7 @@ beginning of the test. It also works for streams, provided that the number of
 channels acquired in *streamer* mode is the same as the number of channels
 acquired by :meth:`~crappy.inout.InOut.get_data`.
 
-**Thing get a bit trickier when the hardware can handle and tune offsets for**
+**Things get a bit trickier when the hardware can handle and tune offsets for**
 **its channels** ! In such a case, it might be advantageous to set the zeroing
 offsets directly on the device rather than relying on Crappy. To achieve that,
 the :meth:`~crappy.inout.InOut.make_zero` method of the base
@@ -171,8 +181,9 @@ these values on the hardware and resets the offsets on Crappy's side. This
 kind of implementation can be found in the :ref:`Labjack T7` or the
 :ref:`Comedi` InOuts. Check their code to see how it looks ! There is also a
 very basic example of offsetting in the `examples on GitHub
-<https://github.com/LaboratoireMecaniqueLille/crappy/examples/custom_objects>`_
-where the method is overriden and the offsets are simply doubled.
+<https://github.com/LaboratoireMecaniqueLille/crappy/tree/master/examples/
+custom_objects>`_ where the method is overriden and the offsets are simply
+doubled.
 
 There is no need for a specific example in this sub-section, it is mostly
 included to signal the existence of the zeroing feature and the possibility for
@@ -181,6 +192,8 @@ users to override it.
 3. More about custom Actuators
 ------------------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 In the tutorial section about :ref:`how to create custom Actuator objects
 <2. Custom Actuators>`, then entire speed management aspect in :py:`position`
 mode was left out. **In this section, we're going to cover in more details**
@@ -225,6 +238,8 @@ examples/blocks>`_.
 4. More about custom Cameras
 ----------------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 Because image acquisition is such a complex topic, the
 :class:`~crappy.camera.Camera` object is by far the richest of the classes
 interfacing with hardware in Crappy. For that reason, not all of its features
@@ -309,7 +324,8 @@ acquired image in order for it to be effective. It returns the cropped image,
 or :obj:`None` if there's nothing left to display (shouldn't happen). You can
 find examples of usage for the software ROI in
 :class:`~crappy.camera.CameraOpencv`, or in the `examples folder on GitHub
-<https://github.com/LaboratoireMecaniqueLille/crappy/examples/blocks>`_.
+<https://github.com/LaboratoireMecaniqueLille/crappy/tree/master/examples/
+blocks>`_.
 
 4.b. Reload slider and choice settings
 ++++++++++++++++++++++++++++++++++++++
@@ -386,6 +402,8 @@ will change in future releases !
 5. Custom Camera Blocks
 -----------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 On the previous tutorial page, :ref:`a section <5. Custom Blocks>` was
 dedicated to the instantiation of custom :ref:`Blocks`. Always moving one step
 further into customization, we're going to see in this section how you can
@@ -673,17 +691,21 @@ that is the final object called by the user in its script. Based on these
 development, here is a final runnable code performing eye detection and adding
 the detected eyes on the displayed images :
 
-.. literalinclude:: /downloads/complex_custom_objects/custom_camera_block.py
-   :language: python
+.. collapse:: (Expand to see the full code)
+
+   .. literalinclude:: /downloads/complex_custom_objects/custom_camera_block.py
+      :language: python
+
+|
 
 .. Note::
    To run this example, you'll need to have the *opencv-python* and *Pillow*
    Python modules installed.
 
 This custom Camera Block script is based on an example that you can find in the
-`custom objects examples folder on GitHub  <https://github.com/
-LaboratoireMecaniqueLille/crappy/examples/custom_objects>`__. You can
-:download:`download it
+`custom objects examples folder on GitHub <https://github.com/
+LaboratoireMecaniqueLille/crappy/tree/master/examples/custom_objects>`__. You
+can :download:`download it
 </downloads/complex_custom_objects/custom_camera_block.py>` to run it locally
 on your machine. Note that the :py:`'Webcam'` camera is used here, so this
 example will require a camera readable by OpenCV to be plugged to the computer.
@@ -696,6 +718,8 @@ aspects in future releases.
 6. Sharing custom objects and Blocks
 ------------------------------------
 
+.. sectionauthor:: Antoine Weisrock <[email protected]>
+
 You have been through all the tutorials of Crappy and have now become a master
 at creating and using your own objects, and you now **want to share your**
 **works with other user** ? No problem ! There are several options for that,