Added auto directives for GVL

DEMCON · Aug 22, 2024 · 62e3064 · 62e3064
1 parent acd8102
commit 62e3064
Show file tree

Hide file tree

Showing 11 changed files with 103 additions and 31 deletions.
diff --git a/docs/plc_code/TwinCAT Project/MyPlcProject/GVLs/GVL_Main.TcGVL b/docs/plc_code/TwinCAT Project/MyPlcProject/GVLs/GVL_Main.TcGVL
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<TcPlcObject Version="1.1.0.1" ProductVersion="3.1.4024.11">
+  <GVL Name="GVL_Main" Id="{3c0591f8-7ec2-40bd-a6ee-66aa6ec345bd}">
+    <Declaration><![CDATA[{attribute 'qualified_only'}
+VAR_GLOBAL
+    flag        : BOOL;             // Flag for the system
+    counter     : ULINT;            // Main counter
+    cycleTIme   : LREAL := 0.001;   // Time between PLC cycles
+END_VAR
+]]></Declaration>
+  </GVL>
+</TcPlcObject>
diff --git a/docs/plc_code/TwinCAT Project/MyPlcProject/MyPlcProject.plcproj b/docs/plc_code/TwinCAT Project/MyPlcProject/MyPlcProject.plcproj
@@ -20,6 +20,10 @@
     <Compile Include="DUTs\ST_ExampleStruct.TcDUT">
       <SubType>Code</SubType>
     </Compile>
+    <Compile Include="GVLs\GVL_Main.TcGVL">
+      <SubType>Code</SubType>
+      <LinkAlways>true</LinkAlways>
+    </Compile>
     <Compile Include="PlcTask.TcTTO">
       <SubType>Code</SubType>
     </Compile>
@@ -71,19 +75,19 @@
   <ProjectExtensions>
     <PlcProjectOptions>
       <XmlArchive>
-  <Data>
-    <o xml:space="preserve" t="OptionKey">
+        <Data>
+          <o xml:space="preserve" t="OptionKey">
       <v n="Name">"&lt;ProjectRoot&gt;"</v>
       <d n="SubKeys" t="Hashtable" />
       <d n="Values" t="Hashtable" />
     </o>
-  </Data>
-  <TypeList>
-    <Type n="Hashtable">System.Collections.Hashtable</Type>
-    <Type n="OptionKey">{54dd0eac-a6d8-46f2-8c27-2f43c7e49861}</Type>
-    <Type n="String">System.String</Type>
-  </TypeList>
-</XmlArchive>
+        </Data>
+        <TypeList>
+          <Type n="Hashtable">System.Collections.Hashtable</Type>
+          <Type n="OptionKey">{54dd0eac-a6d8-46f2-8c27-2f43c7e49861}</Type>
+          <Type n="String">System.String</Type>
+        </TypeList>
+      </XmlArchive>
     </PlcProjectOptions>
   </ProjectExtensions>
 </Project>
diff --git a/docs/src/directives.rst b/docs/src/directives.rst
@@ -414,6 +414,22 @@ autostruct
 .. autostruct:: ST_ExampleStruct
    :noindex:
 
+autogvl
+-------
+
+.. code-block:: rst
+
+   .. autogvl:: <name>
+
+**Examples:**
+
+.. code-block:: rst
+
+   .. autogvl:: GVL_Main
+
+.. autogvl:: GVL_Main
+   :noindex:
+
 autofolder
 ----------
 

diff --git a/src/plcdoc/documenters.py b/src/plcdoc/documenters.py
@@ -533,3 +533,11 @@ def document_members(self, all_members: bool = False) -> None:
                     real_modname="",
                     check_module=False,
                 )
+
+
+class PlcVariableListDocumenter(PlcDataDocumenter):
+
+    objtype = "gvl"
+
+    def format_args(self, **kwargs: Any) -> Optional[str]:
+        return ""  # Do not add arguments like function call
diff --git a/src/plcdoc/extension.py b/src/plcdoc/extension.py
@@ -19,6 +19,7 @@
     PlcStructDocumenter,
     PlcStructMemberDocumenter,
     PlcFolderDocumenter,
+    PlcVariableListDocumenter,
 )
 from .common import _builtin_types_re
 
@@ -60,6 +61,9 @@ def plcdoc_setup(app: Sphinx) -> Dict:
     app.registry.add_documenter("plc:member", PlcStructMemberDocumenter)
     app.add_directive_to_domain("plc", "autostruct", PlcAutodocDirective)
 
+    app.registry.add_documenter("plc:gvl", PlcVariableListDocumenter)
+    app.add_directive_to_domain("plc", "autogvl", PlcAutodocDirective)
+
     app.registry.add_documenter("plc:folder", PlcFolderDocumenter)
     app.add_directive_to_domain("plc", "autofolder", PlcAutodocDirective)
 

diff --git a/src/plcdoc/interpreter.py b/src/plcdoc/interpreter.py
@@ -304,7 +304,7 @@ def __init__(self, meta_model: TextXMetaClass, file=None):
             # extract it from the file name
 
             self._model = meta_model.variable_lists[0]
-            self._objtype = "variable_list"
+            self._objtype = "gvl"
 
         if self._objtype is None:
             raise ValueError(f"Unrecognized declaration in `{meta_model}`")
@@ -387,22 +387,25 @@ def get_args(self, skip_internal=True) -> List:
         :param skip_internal: If true, only return in, out and inout variables
         :retval: Empty list if there are none or arguments are applicable to this type.
         """
-        if not hasattr(self._model, "lists"):
-            return []
-
         args = []
 
-        for var_list in self._model.lists:
-            var_kind = var_list.name.lower()
-            if skip_internal and var_kind not in [
-                "var_input",
-                "var_output",
-                "var_input_output",
-            ]:
-                continue  # Skip internal variables `VAR`
-
-            for var in var_list.variables:
-                var.kind = var_kind
+        if hasattr(self._model, "lists"):
+            for var_list in self._model.lists:
+                var_kind = var_list.name.lower()
+                if skip_internal and var_kind not in [
+                    "var_input",
+                    "var_output",
+                    "var_input_output",
+                ]:
+                    continue  # Skip internal variables `VAR`
+
+                for var in var_list.variables:
+                    var.kind = var_kind
+                    args.append(var)
+
+        if hasattr(self._model, "variables"):
+            for var in self._model.variables:
+                var.kind = "var"
                 args.append(var)
 
         return args

diff --git a/tests/plc_code/TwinCAT PLC/MyPLC/GVLs/GVL_Main.TcGVL b/tests/plc_code/TwinCAT PLC/MyPLC/GVLs/GVL_Main.TcGVL
@@ -8,7 +8,7 @@ Some global variable list.
 Access must include the file name!
 *)
 VAR_GLOBAL
-    someGlobal      : LREAL;    // Descritpion 1
+    someGlobal      : LREAL;    // Description 1
     otherGlobal     : INT;      // Description 2
 END_VAR
 ]]></Declaration>

diff --git a/tests/roots/test-plc-autodoc/conf.py b/tests/roots/test-plc-autodoc/conf.py
@@ -11,6 +11,6 @@
 nitpicky = True
 
 plc_sources = [
-    os.path.join(os.path.abspath("."), item)
-    for item in ["src_plc/*.TcPOU", "src_plc/*.TcDUT"]
+    os.path.join(os.path.abspath("."), "src_plc", item)
+    for item in ["*.TcPOU", "*.TcDUT", "*.TcGVL"]
 ]
diff --git a/tests/roots/test-plc-autodoc/src_plc/AutoGVL.TcGVL b/tests/roots/test-plc-autodoc/src_plc/AutoGVL.TcGVL
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<TcPlcObject Version="1.1.0.1" ProductVersion="3.1.4024.11">
+  <GVL Name="AutoGVL" Id="{3c0591f8-7ec2-40bd-a6ee-66aa6ec345bd}">
+    <Declaration><![CDATA[{attribute 'qualified_only'}
+VAR_GLOBAL
+    flag        : BOOL;             // Flag for the system
+    counter     : ULINT;
+    cycleTime   : LREAL := 0.001;   // Time between PLC cycles
+END_VAR
+]]></Declaration>
+  </GVL>
+</TcPlcObject>
diff --git a/tests/test_interpreter.py b/tests/test_interpreter.py
@@ -25,7 +25,7 @@ class TestPlcInterpreter:
         "POUs/FB_SecondBlock.TcPOU",
         "POUs/MAIN.TcPOU",
         "DUTs/E_Options.TcDUT",
-        "GVL/GVL_Main.TcGVL",
+        "GVLs/GVL_Main.TcGVL",
     ]
 
     def test_files(self, interpreter):
@@ -44,6 +44,7 @@ def test_files(self, interpreter):
             "FB_SecondBlock",
             "MAIN",
             "E_Options",
+            "GVL_Main",
         ]
 
         for name in objects:
@@ -66,7 +67,7 @@ def test_project(self, interpreter):
                 "struct": 12,
                 "function": 5 + 20,  # Functions + Methods
                 "property": 1,
-                "variable_list": 4,
+                "gvl": 4,
             },
         ),
         (
@@ -75,7 +76,7 @@ def test_project(self, interpreter):
                 "functionblock": 32,
                 "struct": 5,
                 "function": 10 + 3,
-                "variable_list": 2,
+                "gvl": 2,
             },
         ),
         (
@@ -86,7 +87,7 @@ def test_project(self, interpreter):
                 "union": 1,
                 "functionblock": 14 + 3,  # Blocks + Interfaces
                 "function": 36 + 138,
-                "variable_list": 3,
+                "gvl": 3,
             },
         ),
     ]

diff --git a/tests/test_plc_autodoc.py b/tests/test_plc_autodoc.py
@@ -144,3 +144,15 @@ def test_autodoc_struct(app, status, warning):
         "      Use as a flag",
         "",
     ] == actual[16:]
+
+
+@pytest.mark.sphinx("html", testroot="plc-autodoc")
+def test_autodoc_gvl(app, status, warning):
+    """Test building a document with the PLC autodoc features."""
+
+    actual = do_autodoc(app, "plc:gvl", "AutoGVL")
+
+    assert ".. plc:gvl:: AutoGVL" == actual[1]
+    assert "   :var BOOL flag: Flag for the system" == actual[4]
+    assert "   :var ULINT counter:" == actual[5]
+    assert "   :var LREAL cycleTime: Time between PLC cycles" == actual[6]