diff --git a/build.sh b/build.sh old mode 100755 new mode 100644 diff --git a/build/templates/rep_caps.rst.mako b/build/templates/rep_caps.rst.mako index 179d56e1fc..350cda6b4f 100644 --- a/build/templates/rep_caps.rst.mako +++ b/build/templates/rep_caps.rst.mako @@ -34,12 +34,18 @@ ${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 +auto_prefix = rep_cap_doc.get('auto_prefix_addition_supported', len(prefix) > 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 auto_prefix: 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 +57,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 diff --git a/build/unit_tests/test_rep_caps_template.py b/build/unit_tests/test_rep_caps_template.py new file mode 100644 index 0000000000..c19a0662be --- /dev/null +++ b/build/unit_tests/test_rep_caps_template.py @@ -0,0 +1,65 @@ +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.', + 'auto_prefix_addition_supported': False, + '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 diff --git a/docs/nidcpower/rep_caps.rst b/docs/nidcpower/rep_caps.rst index 6078e4deab..a828f90261 100644 --- a/docs/nidcpower/rep_caps.rst +++ b/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. - - diff --git a/docs/nidigital/rep_caps.rst b/docs/nidigital/rep_caps.rst index 32550fc4f8..5fc51e899c 100644 --- a/docs/nidigital/rep_caps.rst +++ b/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. - - diff --git a/docs/nifgen/rep_caps.rst b/docs/nifgen/rep_caps.rst index 5890a432ea..030d3d52f4 100644 --- a/docs/nifgen/rep_caps.rst +++ b/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. - - diff --git a/docs/nirfsg/rep_caps.rst b/docs/nirfsg/rep_caps.rst index 4b13100dfa..41fa8018dd 100644 --- a/docs/nirfsg/rep_caps.rst +++ b/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. - - diff --git a/docs/niscope/rep_caps.rst b/docs/niscope/rep_caps.rst index 19169bc085..45c220cccc 100644 --- a/docs/niscope/rep_caps.rst +++ b/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. - - diff --git a/docs/niswitch/rep_caps.rst b/docs/niswitch/rep_caps.rst index 7f141fa26b..c0dde51f4f 100644 --- a/docs/niswitch/rep_caps.rst +++ b/docs/niswitch/rep_caps.rst @@ -34,5 +34,3 @@ channels passes a string of :python:`'0, 1, 2'` to the set attribute function. - - diff --git a/src/nifgen/metadata/attributes.py b/src/nifgen/metadata/attributes.py old mode 100755 new mode 100644 diff --git a/src/nifgen/metadata/config.py b/src/nifgen/metadata/config.py old mode 100755 new mode 100644 diff --git a/src/nifgen/metadata/enums.py b/src/nifgen/metadata/enums.py old mode 100755 new mode 100644 diff --git a/src/nifgen/metadata/functions.py b/src/nifgen/metadata/functions.py old mode 100755 new mode 100644 diff --git a/src/nirfsg/system_tests/ValidWaveformTDMSFile.tdms b/src/nirfsg/system_tests/ValidWaveformTDMSFile.tdms old mode 100755 new mode 100644 diff --git a/src/nirfsg/system_tests/samples2pfile.s2p b/src/nirfsg/system_tests/samples2pfile.s2p old mode 100755 new mode 100644