Error documentation revised

The error documentation outside the class has been made more detailed. This has now been done in the class so that the documentation also appears on the API documentation web page.
Zahner-elektrik · Nov 26, 2024 · 5cdb318 · 5cdb318
1 parent d4886bc
commit 5cdb318
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 38 deletions.
diff --git a/thales_remote/connection.py b/thales_remote/connection.py
@@ -1,4 +1,4 @@
-"""
+r"""
   ____       __                        __    __   __      _ __
  /_  / ___ _/ /  ___  ___ ___________ / /__ / /__/ /_____(_) /__
   / /_/ _ `/ _ \/ _ \/ -_) __/___/ -_) / -_)  '_/ __/ __/ /  '_/

diff --git a/thales_remote/error.py b/thales_remote/error.py
@@ -24,49 +24,59 @@
 THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 """
 
-r"""
-The following is an example for troubleshooting when an exception is thrown.
-
-----Example exception----
-Traceback (most recent call last):
-  File "C:\XXX\Thales-Remote-Python\ie_example.py", line 62, in <module>
-    zahnerZennium.setIESecondEdgePotential(10000)
-  File "C:\XXX\Thales-Remote-Python\ThalesRemote\ThalesRemoteScriptWrapper.py", line 648, in setIESecondEdgePotential
-    return self.setValue("IE_EckPot2", potential)
-  File "C:\XXX\Thales-Remote-Python\ThalesRemote\ThalesRemoteScriptWrapper.py", line 1026, in setValue
-    raise ThalesRemoteError(reply.rstrip("\r") + ThalesRemoteScriptWrapper.undefindedStandardErrorString)
-ThalesRemoteError.ThalesRemoteError: ERROR;100;1
-
-----Explanation----
-
-In the last line you can see what kind of error has occurred:
-
-ThalesRemoteError.ThalesRemoteError: ERROR;100;1
-    ^                                       ^
-    |                                       |
-    |        Error number from the Remote2 manual https://doc.zahner.de/manuals/remote2.pdf
-    |        You can see in the table in chapter 7 of the manual:
-    |        100 | ERROR_PARAMETER_OUT_OF_RANGE | Sent value too low/high
-    |
-    ThalesRemoteError shows that it is an error generated by the library due to a response from the Zenniums containing an error.
-
-The first two lines of the traceback show the file and line number and the content of the line where the error occurred.  
-                          
-  File "C:\XXX\Thales-Remote-Python\ie_example.py", line 62, in <module>
-    zahnerZennium.setIESecondEdgePotential(10000)
-    
-            The error occurred in line 62 of the file ie_example.py with the statement zahnerZennium.setIESecondEdgePotential(10000).
-            This means that the value 10000, which should be set, is out of the allowed range.
-"""
-
 
 class ThalesRemoteError(Exception):
     r"""Thales Remote Exception Class
 
     This exception is thrown when an error is reported in the remote protocol, for example,
     when a parameter is out of range.
-    In the following document the errors are explained.
-    https://doc.zahner.de/manuals/remote2.pdf
+
+    The error numbers can be found in the Remote2 manual in chapter 6 from page 37:
+
+    * Link without line number:
+        * https://doc.zahner.de/manuals/remote2.pdf
+    * Link with line number (may not work with every browser/pdf reader):
+        * https://doc.zahner.de/manuals/remote2.pdf#page=37
+
+    The following is an example for troubleshooting when an exception is thrown.
+
+    **Example exception**
+
+    .. code-block:: bash
+
+        Traceback (most recent call last):
+        File "C:\XXX\Thales-Remote-Python\ie_example.py", line 62, in <module>
+            zahnerZennium.setIESecondEdgePotential(10000)
+        File "C:\XXX\Thales-Remote-Python\ThalesRemote\ThalesRemoteScriptWrapper.py", line 648, in setIESecondEdgePotential
+            return self.setValue("IE_EckPot2", potential)
+        File "C:\XXX\Thales-Remote-Python\ThalesRemote\ThalesRemoteScriptWrapper.py", line 1026, in setValue
+            raise ThalesRemoteError(reply.rstrip("\r") + ThalesRemoteScriptWrapper.undefindedStandardErrorString)
+        ThalesRemoteError.ThalesRemoteError: ERROR;100;1
+
+    **Explanation**
+
+    In the last line you can read what kind of error has occurred:
+
+    .. code-block:: bash
+
+        ThalesRemoteError.ThalesRemoteError: ERROR;100;1
+            ^                                       ^
+            |                                       |
+            |        Error number from the Remote2 manual https://doc.zahner.de/manuals/remote2.pdf
+            |        You can read in the table in chapter 6 of the manual:
+            |        100 | ERROR_PARAMETER_OUT_OF_RANGE | Sent value too low/high
+            |
+            ThalesRemoteError shows that it is an error generated by the library due to a response from the Zenniums containing an error.
+
+    The first two lines of the traceback show the file and line number and the content of the line where the error occurred.
+
+    .. code-block:: bash
+
+        File "C:\XXX\Thales-Remote-Python\ie_example.py", line 62, in <module>
+            zahnerZennium.setIESecondEdgePotential(10000)
+
+    The error occurred in line **62** of the file **ie_example.py** with the statement ``zahnerZennium.setIESecondEdgePotential(10000)``.
+    This means that the value 10000, which should be set, is out of the allowed range.
     """
 
     message: str