Update docs

Ledger-Donjon · Apr 5, 2024 · 2b32b30 · 2b32b30
1 parent bd1ab8d
commit 2b32b30
Show file tree

Hide file tree

Showing 10 changed files with 86 additions and 28 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -9,7 +9,7 @@ version: 2
 build:
   os: "ubuntu-22.04"
   tools:
-    python: "3.8"
+    python: "3.9"
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
-[![Documentation Status](https://readthedocs.org/projects/pystages/badge/?version=latest)](https://pystages.readthedocs.io/en/latest/?badge=latest)
-
 # PyStages
 
+[![Documentation Status](https://readthedocs.org/projects/pystages/badge/?version=latest)](https://pystages.readthedocs.io/en/latest/?badge=latest)
+
 PyStages is a Python 3 library for controlling motorized stages which have a
 motion controller. It has been designed for microscopy test benches automation.
 
@@ -14,17 +14,28 @@ are implemented):
 - Tic Stepper Motor controller (USB only)
 - CNC Router with GRBL/GCode instructions (CNC 3018-PRO)
 
-The library also provides helper classes for basic vector manipulation and 
-autofocus calculation
+The library also provides helper classes for basic vector manipulation and
+autofocus computation.
 
 ## Documentation
 
 Documentation is available on [Read the Docs](https://pystages.readthedocs.io).
 
+## PyStages GUI
+
+A user interface has been implemented to control the stages.
+
+You can run it with the following command:
+
+```bash
+python -m pystages.gui
+```
+
 ## Requirements
 
 This library requires the following packages:
+
 - [pyserial](https://pypi.org/project/pyserial/)
 - [numpy](https://pypi.org/project/numpy/)
 - [pyusb](https://pypi.org/project/pyusb/)
-- [PyQt6](https://pypi.org/project/PyQt6/)
+- [PyQt6](https://pypi.org/project/PyQt6/)
diff --git a/docs/api.rst b/docs/api.rst
@@ -17,10 +17,10 @@ Classes
 .. automodule:: pystages
     :members:
 
-.. autoclass:: Autofocus
-    :members:
+.. .. autoclass:: Autofocus
+..     :members:
 
-.. autoclass:: Vector
-    :special-members: __init__
-    :members:
+.. .. autoclass:: Vector
+..     :special-members: __init__
+..     :members:
 
diff --git a/docs/conf.py b/docs/conf.py
@@ -21,19 +21,19 @@
 # -- Project information -----------------------------------------------------
 
 project = "pystages"
-copyright = "2022, Olivier Hériveaux, Manuel San Pedro, Michaël Mouchous"
+copyright = "2024, Olivier Hériveaux, Manuel San Pedro, Michaël Mouchous"
 author = "Olivier Hériveaux, Manuel San Pedro, Michaël Mouchous"
 
 # The full version, including alpha/beta/rc tags
-release = "1.1"
+release = "1.1.1"
 
 
 # -- 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"]
+extensions = ["sphinx.ext.autodoc", "myst_parser"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -57,3 +57,8 @@
 html_static_path = []
 
 html_logo = "logo.png"
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
diff --git a/docs/gui.md b/docs/gui.md
@@ -0,0 +1,41 @@
+# PyStages GUI
+
+A user interface has been implemented to control the stages.
+
+You can run it with the following command:
+
+```bash
+python -m pystages.gui
+```
+
+This tool presents basic controls. After connection to the stage, it polls the position and prints out
+at the bottom of the window.
+
+## Stage selection and connection
+
+Select the type of stage that you want to control and chose either a serial port to connect to, or select `Auto detect`
+to make pystage to select the correct one according to the device description.
+
+Then click to `Connect`. If the connection success, the control buttons are activated.
+
+## Relative move
+
+You can click on buttons to move for a positive of negative relative distance. 
+The direction correspond to the axis number of the stage (`X` for first axe, `Y` for the second one,
+`Z` for the third one). The moving distance is selected throug the `Step` dropdown menu.
+
+## Absolute move
+
+You can enter absolute coordinates in the 3 entry boxes and trigger the move by clicking the `Go To Position` button.
+
+## Z offset
+
+The `Z offset` checkbox and dropdown menu permit for each horizontal move (X or Y)
+to make first a vertical-up displacement (Z+) followed by the
+actual move, and then a final vertical-down displacement (Z-).
+
+## Homing
+
+The `Home` button permits to trigger the calibration process of the stage. 
+Be careful that your setup is clear before using it.
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,8 +1,3 @@
-.. pystages documentation master file, created by
-   sphinx-quickstart on Tue Jul  7 15:03:18 2020.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to pystages's documentation!
 ====================================
 
@@ -24,13 +19,14 @@ The library also provides helper classes for basic vector manipulation
 (:class:`pystages.Autofocus`).
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-   Vectors <vectors.rst>
-   Autofocus <autofocus.rst>
-   Python API <api.rst>
-   Troubleshooting <troubleshooting.rst>
+  :maxdepth: 2
+  :caption: Contents:
+
+  Vectors <vectors.rst>
+  Autofocus <autofocus.rst>
+  Python API <api.rst>
+  GUI <gui.md>
+  Troubleshooting <troubleshooting.rst>
 
 
 Indices and tables

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -3,3 +3,4 @@ pyusb
 numpy
 sphinx
 sphinx-rtd-theme
+myst-parser
diff --git a/pyproject.toml b/pyproject.toml
@@ -11,7 +11,7 @@ authors = [
 ]
 description = "Motorized stage control library for scientific applications"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",

diff --git a/pystages/cncrouter.py b/pystages/cncrouter.py
@@ -31,6 +31,10 @@
 
 
 class CNCStatus(str, Enum):
+    """
+    Possible statuses that the CNC can report.
+    """
+
     IDLE = "Idle"
     RUN = "Run"
     HOLD = "Hold"

diff --git a/pystages/gui/gui.py b/pystages/gui/gui.py
@@ -169,7 +169,7 @@ def __init__(self):
         self.go_z = w = QLineEdit()
         w.setValidator(v)
         box.addWidget(w)
-        w = QPushButton("Got to position")
+        w = QPushButton("Go to position")
         w.clicked.connect(self.go_to_position)
         self.controls.append(w)
         box.addWidget(w)
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,3 +3,4 @@ pyusb @@
     numpy
     sphinx
     sphinx-rtd-theme
+    myst-parser