Skip to content
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

Jump to bottom

Repeated Capabilites documentation improvements #1686

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

Repeated Capabilites documentation improvements #1686

Show file tree
Hide file tree
Changes from 4 commits
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
56 changes: 38 additions & 18 deletions build/templates/rep_caps.rst.mako
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,16 +19,20 @@

${helper.get_rst_header_snippet('Repeated Capabilities', '=')}

Repeated capabilities attributes are used to set the `channel_string` parameter to the
underlying driver function call. This can be the actual function based on the :py:class:`Session`
method being called, or it can be the appropriate Get/Set Attribute function, such as :c:`${config['c_function_prefix']}SetAttributeViInt32()`.
:py:class:`${module_name}.Session` supports "Repeated Capabilities", which are multiple instances of the same type of
functionality. The repeated capabilities supported by :py:class:`${module_name}.Session` are:

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'`
% for rep_cap in config['repeated_capabilities']:
<%
name = rep_cap['python_name']
%>\
#. ${name}_
% endfor

Use the indexing operator :python:`[]` to indicate which repeated capability you are trying to access.
ni-jfitzger marked this conversation as resolved.
Show resolved Hide resolved
The parameter can be an integer, a string, a list, a tuple, or slice (range).
ni-jfitzger marked this conversation as resolved.
Show resolved Hide resolved

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]`.
ni-jfitzger marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Contributor

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
Contributor

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 +44,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.
ni-jfitzger marked this conversation as resolved.
Show resolved Hide resolved

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

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

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

If an invalid repeated capability is passed to the driver, the driver will return an error.
If an invalid repeated capability is passed to the driver, the driver will return an error.
ni-jfitzger marked this conversation as resolved.
Show resolved Hide resolved

You can also explicitly use the prefix as part of the parameter, but it must be the correct prefix
for the specific repeated capability.
You can also explicitly use the prefix as part of the parameter, but it must be the correct prefix
for the specific repeated capability.

.. 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
.. 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
Collaborator Author

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

42 changes: 30 additions & 12 deletions docs/nidcpower/rep_caps.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,16 +12,16 @@
Repeated Capabilities
=====================

Repeated capabilities attributes are used to set the `channel_string` parameter to the
underlying driver function call. This can be the actual function based on the :py:class:`Session`
method being called, or it can be the appropriate Get/Set Attribute function, such as :c:`niDCPower_SetAttributeViInt32()`.
:py:class:`nidcpower.Session` supports "Repeated Capabilities", which are multiple instances of the same type of
functionality. The repeated capabilities supported by :py:class:`nidcpower.Session` are:

ni-jfitzger marked this conversation as resolved.
Show resolved Hide resolved
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'`
#. channels_
#. instruments_

Some repeated capabilities use a prefix before the number and this is optional
Use the indexing operator :python:`[]` to indicate which repeated capability you are trying to access.
The parameter can be an integer, a string, a list, a tuple, or slice (range).

The recommended way of accessing repeated capabilities is with an integer :python:`[0]` or range :python:`[0:2]`.

channels
--------
Expand All @@ -30,10 +30,19 @@ channels

.. code:: python

session.channels['0-2'].channel_enabled = True
session.channels[0].channel_enabled = True

sets :py:attr:`channel_enabled` to :python:`True` for channels 0.

.. code:: python

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

sets :py:attr:`channel_enabled` to :python:`True` for channels 0, 1, 2.

Copy link
Member

Choose a reason for hiding this comment

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

here is where we could add an example using an iterable, below line 42?

session.channles[range(3)].output_function = nidcpower.OutputFunction.DC_CURRENT

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.

instruments
-----------
Expand All @@ -42,9 +51,18 @@ instruments

.. code:: python

session.instruments['0-2'].channel_enabled = True
session.instruments[0].channel_enabled = True

sets :py:attr:`channel_enabled` to :python:`True` for instruments 0.
ni-jfitzger marked this conversation as resolved.
Show resolved Hide resolved

.. code:: python

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

sets :py:attr:`channel_enabled` to :python:`True` for instruments 0, 1, 2.

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.


Loading