Add documentation for initiate() (#1012)

* Default strings and function to calculate function entry for documentation for initiate

* Make helper function available

* Test helper function

* Use helper function to add documentation for initiate

* Don't add initiate() if there is no session context manager

* Update generated files

* Remove numpy restriction

Bug fixed

* Upgrade pip

* Remove specific version of flake8

'\' in comments now need to be escaped

* Add basepython section

* Try using pypy3.5

* Go back to pypy3 and remove basepython block

* Don't need to run build_test for all builds - only 3.6

* Remove warning from coverage

* Undo previous change

* Try disabling faulthandler

* Remove --no-faulthandler

* pypy needs an older version of pytest

See pytest-dev/pytest#5807

* Use platform_python_implementation since implementation_name is not defined on Python2

* Try to get back to the initial coverage

* Do the same thing for build_test

* Remove redundant pip

* Update comment per review

* Add codecov file to try to control limits for passing

* Fix flake8 errors

build/helper/__init__.py

@@ -24,6 +24,8 @@
 from build.helper.documentation_helper import rep_cap_method_desc_rst  # noqa: F401
 from build.helper.documentation_helper import square_up_tables  # noqa: F401
 
+from build.helper.documentation_snippets import initiate_function_def_for_doc  # noqa: F401
+
 from build.helper.helper import camelcase_to_snakecase  # noqa: F401
 from build.helper.helper import get_array_type_for_api_type  # noqa: F401
 from build.helper.helper import get_numpy_type_for_api_type  # noqa: F401

build/helper/documentation_snippets.py

@@ -96,5 +96,141 @@
 { 'simulate': True, 'driver_setup': { 'Model': '<model number>',  'BoardType': '<type>' } }
 '''
 
+default_initiate_function_doc = '''
+Calls initiate
+'''
+
+initiate_function_note = '''
+This function will return a Python context manager that will initiate on entering and abort on exit.
+'''
+
+
+def initiate_function_def_for_doc(functions, config):
+    # This is very specific to the IVI state model which not all drivers in nimi-python follow.
+    # We look for a 'close' function and if we find it, We will copy that and modify it to be
+    # what we need for documentation
+    session_context_manager_initiate = None
+    if 'initiate_function' in config['context_manager_name']:
+        session_context_manager_initiate = config['context_manager_name']['initiate_function']
+
+    if session_context_manager_initiate is None:
+        # Don't have an initiate
+        return None
+
+    if session_context_manager_initiate in functions:
+        import copy
+        function_def = copy.deepcopy(functions[session_context_manager_initiate])
+        if 'documentation' not in function_def:
+            function_def['documentation'] = {}
+        if 'description' not in function_def['documentation']:
+            function_def['documentation']['description'] = default_initiate_function_doc
+        if 'note' not in function_def['documentation']:
+            function_def['documentation']['note'] = []
+        if type(function_def['documentation']['note']) is not list:
+            function_def['documentation']['note'] = [function_def['documentation']['note']]
+        function_def['documentation']['note'].append(initiate_function_note)
+        function_def['python_name'] = 'initiate'
+    else:
+        function_def = {
+            'documentation': {
+                'description': default_initiate_function_doc,
+                'note': [initiate_function_note],
+            },
+            'method_templates': [
+                {
+                    'documentation_filename': '/default_method',
+                    'method_python_name_suffix': '',
+                    'session_filename': '/default_method',
+                },
+            ],
+            'name': 'initiate',
+            'parameters': [],
+            'has_repeated_capability': False,
+            'python_name': 'initiate',
+            'returns': 'ViStatus',
+        }
+
+    return function_def
+
+
+def test_initiate_function_def_for_doc_no_exist():
+    '''Testing for lack of syntax error - not actual documentation'''
+    functions = {}
+    config = {
+        'context_manager_name': {
+            'task': 'acquisition',
+        },
+    }
+    initiate_doc = initiate_function_def_for_doc(functions, config)
+    assert initiate_doc is None
+    return
+
+
+def test_initiate_function_def_for_doc_note_not_list():
+    '''Testing for lack of syntax error - not actual documentation'''
+    functions = {
+        'Initiate': {
+            'documentation': {
+                'description': 'test',
+                'note': 'test',
+            },
+            'python_name': '_initiate',
+        },
+    }
+    config = {
+        'context_manager_name': {
+            'task': 'acquisition',
+            'initiate_function': 'Initiate',
+            'abort_function': 'Abort',
+        },
+    }
+    initiate_doc = initiate_function_def_for_doc(functions, config)
+    assert type(initiate_doc) is dict
+    return
+
+
+def test_initiate_function_def_for_doc_note_list():
+    '''Testing for lack of syntax error - not actual documentation'''
+    functions = {
+        'Initiate': {
+            'documentation': {
+                'description': 'test',
+                'note': ['test'],
+            },
+            'python_name': '_initiate',
+        },
+    }
+    config = {
+        'context_manager_name': {
+            'task': 'acquisition',
+            'initiate_function': 'Initiate',
+            'abort_function': 'Abort',
+        },
+    }
+    initiate_doc = initiate_function_def_for_doc(functions, config)
+    assert type(initiate_doc) is dict
+    return
+
+
+def test_initiate_function_def_for_doc_no_note():
+    '''Testing for lack of syntax error - not actual documentation'''
+    functions = {
+        'Initiate': {
+            'documentation': {
+                'description': 'test',
+            },
+            'python_name': '_initiate',
+        },
+    }
+    config = {
+        'context_manager_name': {
+            'task': 'acquisition',
+            'initiate_function': 'Initiate',
+            'abort_function': 'Abort',
+        },
+    }
+    initiate_doc = initiate_function_def_for_doc(functions, config)
+    assert type(initiate_doc) is dict
+
 
 

build/templates/class.rst.mako

@@ -6,8 +6,14 @@
     driver_name = config['driver_name']
     c_function_prefix = config['c_function_prefix']
 
-    functions = template_parameters['metadata'].functions
-    functions = helper.filter_public_functions(functions)
+    functions_all = template_parameters['metadata'].functions
+    functions = helper.filter_public_functions(functions_all)
+
+    if 'context_manager_name' in config:
+        # Add a InitiateDoc entry - only used to add initiate() to the Session documentation
+        functions['InitiateDoc'] = helper.initiate_function_def_for_doc(functions_all, config)
+        if functions['InitiateDoc'] is None:
+            functions.pop('InitiateDoc')
 
     doc_list = {}
     for fname in sorted(functions):

build/templates/session.py.mako

@@ -274,9 +274,15 @@ class Session(_SessionBase):
     def __exit__(self, exc_type, exc_value, traceback):
         self.close()
 
+% if session_context_manager is not None:
     def initiate(self):
+        '''initiate
+
+        ${helper.get_function_docstring(helper.initiate_function_def_for_doc(functions, config), False, config, indent=8)}
+        '''
         return ${session_context_manager}(self)
 
+% endif
     def close(self):
         try:
             self._${close_function_name}()

docs/nidcpower/class.rst

@@ -417,6 +417,8 @@ nidcpower.Session
     +--------------------------------------------------+
     | :py:func:`import_attribute_configuration_file`   |
     +--------------------------------------------------+
+    | :py:func:`initiate`                              |
+    +--------------------------------------------------+
     | :py:func:`lock`                                  |
     +--------------------------------------------------+
     | :py:func:`measure`                               |
@@ -6555,6 +6557,32 @@ import_attribute_configuration_file
 
             :type file_path: str
 
+initiate
+~~~~~~~~
+
+    .. py:currentmodule:: nidcpower.Session
+
+    .. py:method:: initiate()
+
+            Starts generation or acquisition, causing the NI-DCPower session to
+            leave the Uncommitted state or Committed state and enter the Running
+            state. To return to the Committed state call the :py:meth:`nidcpower.Session.abort`
+            method. Refer to the `Programming
+            States <REPLACE_DRIVER_SPECIFIC_URL_1(programmingstates)>`__ topic in
+            the *NI DC Power Supplies and SMUs Help* for information about the
+            specific NI-DCPower software states.
+
+            **Related Topics:**
+
+            `Programming
+            States <REPLACE_DRIVER_SPECIFIC_URL_1(programmingstates)>`__
+
+            
+
+            .. note:: This method will return a Python context manager that will initiate on entering and abort on exit.
+
+
+
 lock
 ~~~~
 
@@ -7601,6 +7629,8 @@ Methods
 +--------------------------------------------------------------------+
 | :py:func:`nidcpower.Session.import_attribute_configuration_file`   |
 +--------------------------------------------------------------------+
+| :py:func:`nidcpower.Session.initiate`                              |
++--------------------------------------------------------------------+
 | :py:func:`nidcpower.Session.lock`                                  |
 +--------------------------------------------------------------------+
 | :py:func:`nidcpower.Session.measure`                               |

docs/nidigital/class.rst

@@ -417,6 +417,8 @@ nidigital.Session
     +-------------------------------------------------------------+
     | :py:func:`get_time_set_period`                              |
     +-------------------------------------------------------------+
+    | :py:func:`initiate`                                         |
+    +-------------------------------------------------------------+
     | :py:func:`is_done`                                          |
     +-------------------------------------------------------------+
     | :py:func:`is_site_enabled`                                  |
@@ -5726,6 +5728,21 @@ get_time_set_period
 
 
 
+initiate
+~~~~~~~~
+
+    .. py:currentmodule:: nidigital.Session
+
+    .. py:method:: initiate()
+
+            TBD
+
+            
+
+            .. note:: This method will return a Python context manager that will initiate on entering and abort on exit.
+
+
+
 is_done
 ~~~~~~~
 
@@ -7343,6 +7360,8 @@ Methods
 +-------------------------------------------------------------------------------+
 | :py:func:`nidigital.Session.get_time_set_period`                              |
 +-------------------------------------------------------------------------------+
+| :py:func:`nidigital.Session.initiate`                                         |
++-------------------------------------------------------------------------------+
 | :py:func:`nidigital.Session.is_done`                                          |
 +-------------------------------------------------------------------------------+
 | :py:func:`nidigital.Session.is_site_enabled`                                  |

docs/nidmm/class.rst

@@ -324,6 +324,8 @@ nidmm.Session
     +--------------------------------------------------+
     | :py:func:`import_attribute_configuration_file`   |
     +--------------------------------------------------+
+    | :py:func:`initiate`                              |
+    +--------------------------------------------------+
     | :py:func:`lock`                                  |
     +--------------------------------------------------+
     | :py:func:`perform_open_cable_comp`               |
@@ -3707,6 +3709,25 @@ import_attribute_configuration_file
 
             :type file_path: str
 
+initiate
+~~~~~~~~
+
+    .. py:currentmodule:: nidmm.Session
+
+    .. py:method:: initiate()
+
+            Initiates an acquisition. After you call this method, the DMM leaves
+            the Idle state and enters the Wait-for-Trigger state. If trigger is set
+            to Immediate mode, the DMM begins acquiring measurement data. Use
+            :py:meth:`nidmm.Session.fetch`, :py:meth:`nidmm.Session.fetch_multi_point`, or :py:meth:`nidmm.Session.fetch_waveform` to
+            retrieve the measurement data.
+
+            
+
+            .. note:: This method will return a Python context manager that will initiate on entering and abort on exit.
+
+
+
 lock
 ~~~~
 
@@ -4409,6 +4430,8 @@ Methods
 +----------------------------------------------------------------+
 | :py:func:`nidmm.Session.import_attribute_configuration_file`   |
 +----------------------------------------------------------------+
+| :py:func:`nidmm.Session.initiate`                              |
++----------------------------------------------------------------+
 | :py:func:`nidmm.Session.lock`                                  |
 +----------------------------------------------------------------+
 | :py:func:`nidmm.Session.perform_open_cable_comp`               |

docs/nifgen/class.rst

@@ -444,6 +444,8 @@ nifgen.Session
     +-----------------------------------------------------+
     | :py:func:`get_self_cal_supported`                   |
     +-----------------------------------------------------+
+    | :py:func:`initiate`                                 |
+    +-----------------------------------------------------+
     | :py:func:`is_done`                                  |
     +-----------------------------------------------------+
     | :py:func:`lock`                                     |
@@ -5817,6 +5819,24 @@ get_self_cal_supported
 
 
 
+initiate
+~~~~~~~~
+
+    .. py:currentmodule:: nifgen.Session
+
+    .. py:method:: initiate()
+
+            Initiates signal generation. If you want to abort signal generation,
+            call the :py:meth:`nifgen.Session.abort` method. After the signal generation
+            is aborted, you can call the :py:meth:`nifgen.Session.initiate` method to
+            cause the signal generator to produce a signal again.
+
+            
+
+            .. note:: This method will return a Python context manager that will initiate on entering and abort on exit.
+
+
+
 is_done
 ~~~~~~~
 
@@ -6761,6 +6781,8 @@ Methods
 +--------------------------------------------------------------------+
 | :py:func:`nifgen.Session.get_self_cal_supported`                   |
 +--------------------------------------------------------------------+
+| :py:func:`nifgen.Session.initiate`                                 |
++--------------------------------------------------------------------+
 | :py:func:`nifgen.Session.is_done`                                  |
 +--------------------------------------------------------------------+
 | :py:func:`nifgen.Session.lock`                                     |