better xrefs and adapt sources stored here to new spec

Author: birkenfeld

secop_sphinx.py

@@ -16,20 +16,21 @@ def handle_signature(self, sig, signode):
         signode.insert(0, addnodes.desc_addname('', 'Property',
                                                 addnodes.desc_sig_space()))
         if self.name == 'node-property':
-            fullname = 'node:' + fullname
+            fullname = 'node.' + fullname
         elif self.name == 'mod-property':
-            fullname = 'mod:' + fullname
+            fullname = 'mod.' + fullname
         return fullname, prefix
 
     def get_index_text(self, modname, name_cls):
+        name = name_cls[0].rpartition('.')[2]
         if self.name == 'node-property':
-            return '%s (node property)' % name_cls[0]
+            return f'{name} (node property)'
         elif self.name == 'mod-property':
-            return '%s (module property)' % name_cls[0]
+            return f'{name} (module property)'
         elif self.name == 'acc-property':
-            return '%s (accessible property)' % name_cls[0]
+            return f'{name} (accessible property)'
         else:
-            return '%s (property)' % name_cls[0]
+            return f'{name} (property)'
 
 
 class Parameter(PyVariable):

source/conf.py

@@ -35,6 +35,7 @@
 # -- General configuration ---------------------------------------------------
 
 default_role = 'obj'
+nitpicky = True
 
 highlight_language = 'secop'
 

source/getting-started/first-use.rst

@@ -17,9 +17,8 @@ Talking to a SEC node
 
 So you have never used SECoP, and want to interact with a node?  For exploring
 the protocol, all you need is a program that can talk tcp or serial, depending
-on your device.  Connect to your device and send the :ref:`identification
-message <message-identification>` ``*IDN?`` to start communication ('>' and '<'
-show who is sending the message):
+on your device.  Connect to your device and send the `*IDN?` identification
+message to start communication ('>' and '<' show who is sending the message):
 
 .. code::
 
@@ -30,7 +29,7 @@ speak:
 
 .. code::
 
-    < ISSE,SECoP,V2019-09-16,v1.0
+    < ISSE,SECoP,,v2.0
 
 Great!  So we know that we are talking to something that knows SECoP, but we do
 not know yet what we are talking to.  That is what we will find out with next
@@ -265,8 +264,8 @@ module.
 The ``accessibles`` field lists all parameters that are defined on the module
 and can be accessed over SECoP.  In the block above, you can see ``value`` and
 ``status`` two parameters which almost all modules will have.  The precise
-semantics of all such parameters are defined in :ref:`the specification
-<accessibles>`.
+semantics of all such parameters are defined in :doc:`the specification
+</specification/accessibles>`.
 
 The value is the current value of the module, and the status is a two-element
 tuple of a status code and a message that can give more information about the
@@ -333,8 +332,8 @@ knowledge, we can interact with specific parts of it.
 Reading values
 ^^^^^^^^^^^^^^
 
-The most basic command to access a module is the :ref:`read <message-read>`
-message, where we can retrieve the value of a parameter:
+The most basic command to access a module is the `read` message, where we can
+retrieve the value of a parameter:
 
 .. code::
 
@@ -351,7 +350,7 @@ Writing values
 ^^^^^^^^^^^^^^
 
 If we want to set a value, for example the ``_maxheaterpower`` of the ``heater``
-we can use the :ref:`change <message-change>` message:
+we can use the `change` message:
 
 .. code::
 
@@ -375,7 +374,7 @@ error string giving more information, and some qualifiers (in this case, none).
 Running commands
 ^^^^^^^^^^^^^^^^
 
-Running a command is done with the :ref:`do <message-do>` message:
+Running a command is done with the `do` message:
 
 .. code::
 
@@ -400,8 +399,8 @@ have a look at the status.  It will go ``BUSY`` until the change is done.  When
 it returns to ``IDLE`` then the action is finished.
 
 The other commands won't be discussed here, but as a pointer have a look at
-:ref:`activate <message-activate>` which enables asynchronous mode.  That gives
-you a stream of updates for all parameters of a SEC node without polling.
+`activate` which enables asynchronous mode.  That gives you a stream of updates
+for all parameters of a SEC node without polling.
 
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

source/getting-started/with-shall.rst

@@ -3,39 +3,39 @@ Getting started: SHALL-LabVIEW
 
 This section will give you an overview of the SHALL-LabVIEW integration for SECoP
 
-The package allows the creation of SEC nodes in LabVIEW. It's interface is designed 
-to be easily integrated into existing projects. The package uses the 
-`SHALL <https://github.com/SampleEnvironment/SHALL>`_ libraries at its core to handle 
+The package allows the creation of SEC nodes in LabVIEW. It's interface is designed
+to be easily integrated into existing projects. The package uses the
+`SHALL <https://github.com/SampleEnvironment/SHALL>`_ libraries at its core to handle
 all SECoP communication and message handling.
 
-**Note: The VIs in this project have been built using LabVIEW 2023. The Releases 
+**Note: The VIs in this project have been built using LabVIEW 2023. The Releases
 are also available for LabVIEW2019 in the Release Assets.**
 
 Installation
 ------------
 
-1. Getting the Source  
+1. Getting the Source
 ~~~~~~~~~~~~~~~~~~~~~
 
-You can either clone the project directly, which will give you the latest version of 
-the project, or select a `Release <https://github.com/SampleEnvironment/SHALL-LabVIEW/releases>`_ , 
+You can either clone the project directly, which will give you the latest version of
+the project, or select a `Release <https://github.com/SampleEnvironment/SHALL-LabVIEW/releases>`_ ,
 where you can also download a version that has been exported for LabVIEW 2019.
 
 Clone the Repository:
 .. code:: bash
-    
+
     git clone https://github.com/SampleEnvironment/SHALL-LabVIEW.git
 
-Depending on your LabVIEW version you will able to use the Project as is, or export it 
-for the specific version of LabVIEW you have installed.  
+Depending on your LabVIEW version you will able to use the Project as is, or export it
+for the specific version of LabVIEW you have installed.
 
-2. Setting Up the Platforms Folder 
+2. Setting Up the Platforms Folder
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In order for the Qt libraries to work properly, a **softlink** must be created to the **platforms** folder 
-(``PLATFORMS_PATH = ./shall-labview/[32bit|64bit]/platforms``) inside your LabVIEW installation directory. 
+In order for the Qt libraries to work properly, a **softlink** must be created to the **platforms** folder
+(``PLATFORMS_PATH = ./shall-labview/[32bit|64bit]/platforms``) inside your LabVIEW installation directory.
 
-First, determine if you have the 32-bit or 64-bit version of LabVIEW installed. And where the installation 
+First, determine if you have the 32-bit or 64-bit version of LabVIEW installed. And where the installation
 directory is. From here on I will refer to the installation directory as ``LABVIEW_PATH``:
 
 - **32bit** is usually located under:
@@ -52,46 +52,42 @@ Next you also need the path ``PLATFORMS_PATH`` to the correct platforms folder :
 
 Finally, create the symbolic link inside the LabVIEW installation directory
 
-.. code:: 
+.. code::
 
     mklink /d LABVIEW_PATH\platforms PLATFORMS_PATH
 
-3. Check your installation 
+3. Check your installation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To check if your installation was successful, you can open the ``SECoP.lvproj`` project file and 
-open ``random-demo/dcy03.vi`` before running the VI, the correct DLL path must be entered. 
+To check if your installation was successful, you can open the ``SECoP.lvproj`` project file and
+open ``random-demo/dcy03.vi`` before running the VI, the correct DLL path must be entered.
 
 
 
 
-It is the same as `PLATFORMS_PATH` minus the `/platforms` postfix. 
+It is the same as ``PLATFORMS_PATH`` minus the ``/platforms`` postfix.
 It should look something like this:
 
 .. image:: https://github.com/user-attachments/assets/8659c9a4-fd4a-4949-a38d-d4110855eadf
 
 
-.. code:: 
+.. code::
 
     D:\shall-repos\shall-labview\64bit
 
 or
 
-.. code:: 
-    
+.. code::
+
     D:\shall-repos\shall-labview\32bit
 
 
-If you entered the DLL path correctly and run the Vi, a small `SECoP Status` window should open. 
+If you entered the DLL path correctly and run the Vi, a small "SECoP Status" window should open.
 
 
 
 Creating a SEC Node
 -------------------
 
-For a detailed tutorial on how to create and manage SEC nodes using SHALL-LabVIEW 
+For a detailed tutorial on how to create and manage SEC nodes using SHALL-LabVIEW
 please refer to the SHALL-LabVIEW `Wiki <https://github.com/SampleEnvironment/SHALL-LabVIEW/wiki>`_.
-
-
-
-