add override capabilities to repeated capabilities documentation

build/templates/rep_caps.rst.mako

@@ -34,12 +34,17 @@ ${helper.get_rst_header_snippet('Repeated Capabilities', '=')}
 <%
 name = rep_cap['python_name']
 prefix = rep_cap['prefix']
+rep_cap_doc = rep_cap.get('documentation', {})
+has_custom_doc = len(rep_cap_doc) > 0
 %>\
 ${helper.get_rst_header_snippet(name, '-')}
 
     .. py:attribute:: ${module_name}.Session.${name}[]
 
-% if len(prefix) > 0:
+% if has_custom_doc and 'description' in rep_cap_doc:
+        ${rep_cap_doc['description']}
+
+% elif len(prefix) > 0:
         If no prefix is added to the items in the parameter, the correct prefix will be added when
         the driver function call is made.
 
@@ -51,16 +56,30 @@ ${helper.get_rst_header_snippet(name, '-')}
 
         If an invalid repeated capability is passed to the driver, the driver will return an error.
 
+% if len(prefix) > 0:
         You can also explicitly use the prefix as part of the parameter, but it must be the correct prefix
         for the specific repeated capability.
 
 % endif
+% endif
+% if not has_custom_doc or 'examples' not in rep_cap_doc:
         .. code:: python
 
             session.${name}['${prefix}0-${prefix}2'].channel_enabled = True
 
         passes a string of :python:`'${prefix}0, ${prefix}1, ${prefix}2'` to the set attribute function.
 
+% endif
+% if has_custom_doc and 'valid_identifiers' in rep_cap_doc and len(rep_cap_doc['valid_identifiers']) > 0:
+        Valid identifiers: :python:`'${", ".join(rep_cap_doc["valid_identifiers"])}'`.
 
-% endfor
+% endif
+% if has_custom_doc and 'examples' in rep_cap_doc and len(rep_cap_doc['examples']) > 0:
+% for example in rep_cap_doc['examples']:
+        .. code:: python
+
+            ${example}
 
+% endfor
+% endif
+% endfor

build/unit_tests/test_rep_caps_template.py

@@ -0,0 +1,64 @@
+from pathlib import Path
+from types import SimpleNamespace
+
+from mako.template import Template
+
+
+def _render_rep_caps(config):
+    repo_root = Path(__file__).resolve().parents[2]
+    template_path = repo_root / 'build' / 'templates' / 'rep_caps.rst.mako'
+    template = Template(filename=str(template_path))
+    metadata = SimpleNamespace(config=config)
+    return template.render(template_parameters={'metadata': metadata})
+
+
+def test_rep_caps_template_uses_custom_documentation_overrides():
+    config = {
+        'module_name': 'nifake',
+        'c_function_prefix': 'niFake_',
+        'repeated_capabilities': [
+            {
+                'prefix': 'res',
+                'python_name': 'resources',
+                'documentation': {
+                    'description': 'Resource repeated capabilities use fully-qualified identifiers.',
+                    'valid_identifiers': ['dev0/res0', 'dev0/res1'],
+                    'examples': [
+                        "session.resources['dev0/res0'].channel_enabled = True",
+                        "session.resources['dev0/res1'].channel_enabled = True",
+                    ],
+                },
+            }
+        ],
+    }
+
+    rendered = _render_rep_caps(config)
+
+    assert 'Resource repeated capabilities use fully-qualified identifiers.' in rendered
+    assert "Valid identifiers: :python:`'dev0/res0, dev0/res1'`." in rendered
+    assert "session.resources['dev0/res0'].channel_enabled = True" in rendered
+    assert "session.resources['dev0/res1'].channel_enabled = True" in rendered
+
+    # Generic auto-prefix guidance should be suppressed when override disables it.
+    assert 'If no prefix is added to the items in the parameter' not in rendered
+    assert "session.resources['0-2'].channel_enabled = True" not in rendered
+    assert "'res0, res1, res2'" not in rendered
+
+
+def test_rep_caps_template_preserves_default_prefixed_behavior():
+    config = {
+        'module_name': 'nifake',
+        'c_function_prefix': 'niFake_',
+        'repeated_capabilities': [
+            {
+                'prefix': 'channel',
+                'python_name': 'channels',
+            }
+        ],
+    }
+
+    rendered = _render_rep_caps(config)
+
+    assert 'If no prefix is added to the items in the parameter' in rendered
+    assert "session.channels['0-2'].channel_enabled = True" in rendered
+    assert "'channel0, channel1, channel2'" in rendered

docs/nidcpower/rep_caps.rst

@@ -34,7 +34,6 @@ channels
 
         passes a string of :python:`'0, 1, 2'` to the set attribute function.
 
-
 instruments
 -----------
 
@@ -46,5 +45,3 @@ instruments
 
         passes a string of :python:`'0, 1, 2'` to the set attribute function.
 
-
-

docs/nidigital/rep_caps.rst

@@ -34,7 +34,6 @@ channels
 
         passes a string of :python:`'0, 1, 2'` to the set attribute function.
 
-
 pins
 ----
 
@@ -46,7 +45,6 @@ pins
 
         passes a string of :python:`'0, 1, 2'` to the set attribute function.
 
-
 instruments
 -----------
 
@@ -58,7 +56,6 @@ instruments
 
         passes a string of :python:`'0, 1, 2'` to the set attribute function.
 
-
 pattern_opcode_events
 ---------------------
 
@@ -84,7 +81,6 @@ pattern_opcode_events
 
         passes a string of :python:`'patternOpcodeEvent0, patternOpcodeEvent1, patternOpcodeEvent2'` to the set attribute function.
 
-
 conditional_jump_triggers
 -------------------------
 
@@ -110,7 +106,6 @@ conditional_jump_triggers
 
         passes a string of :python:`'conditionalJumpTrigger0, conditionalJumpTrigger1, conditionalJumpTrigger2'` to the set attribute function.
 
-
 sites
 -----
 
@@ -136,7 +131,6 @@ sites
 
         passes a string of :python:`'site0, site1, site2'` to the set attribute function.
 
-
 rio_events
 ----------
 
@@ -162,7 +156,6 @@ rio_events
 
         passes a string of :python:`'RIOEvent0, RIOEvent1, RIOEvent2'` to the set attribute function.
 
-
 rio_triggers
 ------------
 
@@ -188,5 +181,3 @@ rio_triggers
 
         passes a string of :python:`'RIOTrigger0, RIOTrigger1, RIOTrigger2'` to the set attribute function.
 
-
-

docs/nifgen/rep_caps.rst

@@ -34,7 +34,6 @@ channels
 
         passes a string of :python:`'0, 1, 2'` to the set attribute function.
 
-
 script_triggers
 ---------------
 
@@ -60,7 +59,6 @@ script_triggers
 
         passes a string of :python:`'ScriptTrigger0, ScriptTrigger1, ScriptTrigger2'` to the set attribute function.
 
-
 markers
 -------
 
@@ -86,7 +84,6 @@ markers
 
         passes a string of :python:`'Marker0, Marker1, Marker2'` to the set attribute function.
 
-
 data_markers
 ------------
 
@@ -112,5 +109,3 @@ data_markers
 
         passes a string of :python:`'DataMarker0, DataMarker1, DataMarker2'` to the set attribute function.
 
-
-

docs/nirfsg/rep_caps.rst

@@ -48,7 +48,6 @@ markers
 
         passes a string of :python:`'marker0, marker1, marker2'` to the set attribute function.
 
-
 script_triggers
 ---------------
 
@@ -74,7 +73,6 @@ script_triggers
 
         passes a string of :python:`'scripttrigger0, scripttrigger1, scripttrigger2'` to the set attribute function.
 
-
 waveforms
 ---------
 
@@ -100,7 +98,6 @@ waveforms
 
         passes a string of :python:`'waveform::0, waveform::1, waveform::2'` to the set attribute function.
 
-
 ports
 -----
 
@@ -112,7 +109,6 @@ ports
 
         passes a string of :python:`'0, 1, 2'` to the set attribute function.
 
-
 los
 ---
 
@@ -138,7 +134,6 @@ los
 
         passes a string of :python:`'LO0, LO1, LO2'` to the set attribute function.
 
-
 device_temperatures
 -------------------
 
@@ -150,7 +145,6 @@ device_temperatures
 
         passes a string of :python:`'0, 1, 2'` to the set attribute function.
 
-
 channels
 --------
 
@@ -162,5 +156,3 @@ channels
 
         passes a string of :python:`'0, 1, 2'` to the set attribute function.
 
-
-

docs/niscope/rep_caps.rst

@@ -34,7 +34,6 @@ channels
 
         passes a string of :python:`'0, 1, 2'` to the set attribute function.
 
-
 instruments
 -----------
 
@@ -46,5 +45,3 @@ instruments
 
         passes a string of :python:`'0, 1, 2'` to the set attribute function.
 
-
-

docs/niswitch/rep_caps.rst

@@ -34,5 +34,3 @@ channels
 
         passes a string of :python:`'0, 1, 2'` to the set attribute function.
 
-
-