Skip to content

Repeated Capabilites documentation improvements #1686

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ni-jfitzger wants to merge 21 commits into
base: master
Choose a base branch
from
Open

Repeated Capabilites documentation improvements #1686

Changes from 1 commit
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
e9b6f72
Repeated Capabilites documentation improvements
ni-jfitzger Jan 21, 2022
7b3a1a5
codegen with rep_caps.rst changes
ni-jfitzger Jan 24, 2022
8bc69bc
Remove comment containing tips we decided weren't useful
ni-jfitzger Jan 28, 2022
93d62f1
Update general description of repeated capabilities.
ni-jfitzger Jan 28, 2022
e4ba124
Merge branch 'master' of https://github.com/ni-jfitzger/nimi-python i…
ni-jfitzger Apr 3, 2023
4fda89a
indexing is for repeated capability **instance**
ni-jfitzger Apr 3, 2023
948db7a
Remove commented section for non-0-length prefixes
ni-jfitzger Apr 3, 2023
f2dc5ea
Merge branch 'master' of https://github.com/ni-jfitzger/nimi-python i…
ni-jfitzger May 6, 2023
f04652c
Merge branch 'master' of https://github.com/ni-jfitzger/nimi-python i…
ni-jfitzger Jul 11, 2023
d48cfc9
generate correct snippets for nidigital
ni-jfitzger Jul 11, 2023
1cc9cf4
generate correct rep cap documentation for nidcpower
ni-jfitzger Jul 11, 2023
ce93c56
generate correct rep cap documentation for nifgen
ni-jfitzger Jul 11, 2023
8e8833c
merge indices, string_indices fields
ni-jfitzger Jul 11, 2023
cf13613
genereate correct rep cap documentation for niscope
ni-jfitzger Jul 11, 2023
76fede8
generate correct rep_cap documentation for niswitch
ni-jfitzger Jul 11, 2023
fb8c3a0
parameterize the new tests
ni-jfitzger Jul 11, 2023
ad59a96
reduce code duplication in new helper functions
ni-jfitzger Jul 11, 2023
30efefd
eliminate most rep cap example defaults
ni-jfitzger Jul 11, 2023
e461d65
Omit examples of elements and iterables at the top. Specify element t…
ni-jfitzger Jul 15, 2023
19b2208
Remove the "or errors if the value is not the same for all." statement
ni-jfitzger Jul 15, 2023
d2c61ae
like -> such as
ni-jfitzger Jul 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 34 additions & 13 deletions build/templates/rep_caps.rst.mako
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,15 @@ ${helper.get_rst_header_snippet('Repeated Capabilities', '=')}

Repeated capabilities attributes use the indexing operator :python:`[]` to indicate the repeated capabilities.
The parameter can be a string, list, tuple, or slice (range). Each element of those can be a string or
an integer. If it is a string, you can indicate a range using the same format as the driver: :python:`'0-2'` or
:python:`'0:2'`
an integer.

Some repeated capabilities use a prefix before the number and this is optional
..
If it is a string, you can indicate a range using the same format as the driver: :python:`'0-2'` or
:python:`'0:2'`

Some repeated capabilities use a prefix before the number and this is optional.

The recommended way of accessing repeated capabilities is with an integer :python:`[0]` or range :python:`[0:2]`.
Comment thread
ni-jfitzger marked this conversation as resolved.
Outdated
Copy link
Copy Markdown
Contributor

@sbethur sbethur Jan 29, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

range :python:[0:2]

I don't think this will work since this is not the correct syntax for Python range. But ['0:2'] will work because of the custom logic we have for handling range-based strings.

Having said that, I don't think any of the ways I've enumerated above can be recommended over others. int is obviously the go-to for single instances. Basic sequence types and slice are good to use because they're part of the language, Range-based strings provides syntactic sugar for defining ranges. e.g. ['0:2'] rather than [range(0,2)].

Copy link
Copy Markdown
Contributor

@sbethur sbethur Jan 29, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see @marcoskirsch doesn't like us to recommend the range-based strings. Since I saw we had logic specifically for handling it, I thought it was important. But it sounds like it was ill-conceived. I don't mind not documenting it.

Once we land on recommended ways, we should go over the examples to ensure only recommended types are used.


% for rep_cap in config['repeated_capabilities']:
<%
Expand All @@ -40,27 +45,43 @@ ${helper.get_rst_header_snippet(name, '-')}
.. py:attribute:: ${module_name}.Session.${name}[]

% if 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.
..
If no prefix is added to the items in the parameter, the correct prefix will be added when
the driver function call is made.
Comment thread
ni-jfitzger marked this conversation as resolved.
Outdated

.. code:: python
.. code:: python

session.${name}['0-2'].channel_enabled = True

passes a string of :python:`'${prefix}0, ${prefix}1, ${prefix}2'` to the set attribute function.
Comment thread
ni-jfitzger marked this conversation as resolved.
Outdated

session.${name}['0-2'].channel_enabled = True
If an invalid repeated capability is passed to the driver, the driver will return an error.
Comment thread
ni-jfitzger marked this conversation as resolved.
Outdated

passes a string of :python:`'${prefix}0, ${prefix}1, ${prefix}2'` to the set attribute function.
You can also explicitly use the prefix as part of the parameter, but it must be the correct prefix
for the specific repeated capability.

If an invalid repeated capability is passed to the driver, the driver will return an error.
.. code:: python

You can also explicitly use the prefix as part of the parameter, but it must be the correct prefix
for the specific repeated capability.
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
.. code:: python

session.${name}['${prefix}0-${prefix}2'].channel_enabled = True
session.${name}[0].channel_enabled = True

sets :py:attr:`channel_enabled` to :python:`True` for ${name} 0.

.. code:: python

passes a string of :python:`'${prefix}0, ${prefix}1, ${prefix}2'` to the set attribute function.
session.${name}[0:2].channel_enabled = True

sets :py:attr:`channel_enabled` to :python:`True` for ${name} 0, 1, 2.
Copy link
Copy Markdown
Collaborator Author

@ni-jfitzger ni-jfitzger Jan 21, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I add anything to the recommend types above, I should add an example usage, here.


Note that :py:attr:`channel_enabled` is only used as an example and is not necessarily a property which
supports this repeated capability. See documentation for individual properties and methods to
learn what repeated capabilites they support, if any.

% endfor