Clean up nitclk docs (#1043)

* Add initial metadata

* Create nitclk.mak

* 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

* Add codecov file to try to control limits for passing

* Enable nitclk build

* There are some files we will need to skip for now

* Add generated nitclk files

* Update generated files

* Can't skip README.rst

* Update templates

* Add new cases for buffers with a converter

* Need to handle ' []' to normalize everything

* Get the session handle name from config instead of hardcoding 'vi'

* Temp commit

* Fix syntax error

* Test new cases

* Force change

* Update generated files

* Update generated files

* Add different target for pr (project) and commit (patch)

* threshold should be number

* Renumber scaler cases to be in order used in the code

* Update generated files

* Renumber buffer cases to match order used in code

* Move and rename test to match case (C020)

* Update generated files

* Add nitclk specific session template

* No longer need to skip generating session.py

* Add new session.py

* Add placeholder nitclk example

* Enable example documentation build

* Add generated examples.rst

* Add TClk to static files

* Add tclk to index

* Add tclk top level file

* Update generated files

* Add VIUInt32 matcher

* Add ViSession buffer matcher

* We want to look at all of nitclk since there are differences in some of the generarted files

* Run unit tests on nitclk

* Add initial test and setup

* Update generated files

* Correct wrong exception

* Rename test

* Add return (helps editor auto formatting)

* Update generated files

* Few more tests

* Add new filter type

Needed for API functions in nitclk

* Don't try to use a singleton any more - didn't work

* Use new filter type

* All API functions tested

This covers both the api function and the helper class

* Update generated files

* Fix metadata for GetAttributeViString

* More tests!

* Correct type is ViSession

* Need to say it isn't the session handle

* Test class for testing session number converter

* Additional tests

* Update generated files

* We don't need to measure anything from nitclk or nimodinst other than session.py

* Fix class names to work with pytest

* Use correct name

* Don't codegen ViBoolean functions since they aren't actually used

* Update generated files

* Handle not having an 'init_function' in config

* Remove InitForDocumentation

* Add tclk specific class.rst template

* Updates

* Build using nitclk specific class.rst template

* Add type in documentation

* Fix output path

* Documentation updates

* We need to be able to use method or function, default is method

* Links need to be different for nitclk

* Clean up nitclk class documentation

* Put functions first (properties are an advanced feature)
* Do a better job with headers that show up in the TOC
* Basic documentation for Public API and SessionReference

* Update generated files

* Update generated files

* Use the session name from config - doesn't always match the parameter name

* Update converter name

* Need a reperated capabilities for get/set attribute

* Function is now private

* Update generated files

* Update

* Remove extraneous comment

* Only add properties section if there are actually properties

* Update to match latest format in master

* Update generated files

* Use the entire navigation depth

* Remove unused parameter

* Clarify docstring

* Fix example code to actually work

* Update NI-TClk description

* Update generated files

* Lower target for patch

.codecov.yml

@@ -10,7 +10,7 @@ coverage:
         threshhold: 5
     patch:
       default:
-        target: 85%
+        target: 70%
         threshhold: 5
 
 

build/helper/documentation_helper.py

@@ -352,7 +352,10 @@ def _replace_attribute_python_name(a_match):
             aname = attr['name'].lower()
 
     if config['make_link']:
-        return ':py:data:`{0}.Session.{1}`'.format(config['module_name'], aname)
+        if config['module_name'] == 'nitclk':
+            return ':py:attr:`{0}.SessionReference.{1}`'.format(config['module_name'], aname)
+        else:
+            return ':py:data:`{0}.Session.{1}`'.format(config['module_name'], aname)
     else:
         return '{0}'.format(aname)
 
@@ -381,7 +384,10 @@ def _replace_func_python_name(f_match):
         print(config['functions'])
 
     if config['make_link']:
-        return ':py:meth:`{0}.Session.{1}`'.format(config['module_name'], fname)
+        if config['module_name'] == 'nitclk':
+            return ':py:func:`{0}.{1}`'.format(config['module_name'], fname)
+        else:
+            return ':py:meth:`{0}.Session.{1}`'.format(config['module_name'], fname)
     else:
         return '{0}'.format(fname)
 
@@ -491,8 +497,8 @@ def format_type_for_rst_documentation(param, numpy, config):
     return p_type
 
 
-def get_function_rst(function, method_template, numpy, config, indent=0):
-    '''Gets formatted documentation for given function that can be used in rst documentation
+def get_function_rst(function, method_template, numpy, config, indent=0, method_or_function='method'):
+    '''Gets formatted documentation for given function or method that can be used in rst documentation
 
     Args:
         function (dict): function dictionary
@@ -515,7 +521,7 @@ def get_function_rst(function, method_template, numpy, config, indent=0):
     if function['has_repeated_capability'] is True:
         function['documentation']['tip'] = rep_cap_method_desc_rst.format(config['module_name'], function['repeated_capability_type'], function['python_name'], get_params_snippet(function, session_method))
 
-    rst = '.. py:method:: ' + function['python_name'] + suffix + '('
+    rst = '.. py:{0}:: {1}{2}('.format(method_or_function, function['python_name'], suffix)
     rst += get_params_snippet(function, session_method) + ')'
     indent += 4
     rst += get_documentation_for_node_rst(function, config, indent)

build/helper/metadata_add_all.py

@@ -335,8 +335,12 @@ def _setup_init_function(functions, config):
 
         functions['_init_function'] = init_function
     except KeyError:
-        print("Couldn't find {} init function".format(config['init_function']))
-        pass
+        if 'init_function' not in config or config['init_function'] is None:
+            # We don't have an init function or it is set to None (same thing) so we can't
+            # do anything here
+            pass
+        else:
+            print("Couldn't find {} init function".format(config['init_function']))
 
 
 def add_all_function_metadata(functions, config):

build/templates/class.rst.mako

@@ -62,11 +62,10 @@ ${helper.get_rst_header_snippet(item, '-')}
 
 % endfor
 
+% if len(attributes) > 0:
 ${helper.get_rst_header_snippet('Properties', '=')}
 
 % for attr in helper.sorted_attrs(attributes):
-<% # ${helper.get_rst_header_snippet(attributes[attr]["python_name"], '~')}
-%>\
 ${helper.get_rst_header_snippet(attributes[attr]['python_name'], '-')}
 
     .. py:attribute:: ${attributes[attr]["python_name"]}
@@ -101,6 +100,7 @@ desc = helper.get_documentation_for_node_rst(a, config, indent=0)
                 - C Attribute: **${c_function_prefix.upper()}ATTR_${attributes[attr]["name"].upper()}**
 
 % endfor
+% endif
 
 .. contents:: Session
 

build/templates/conf.py.mako

@@ -103,7 +103,9 @@ html_theme = 'sphinx_rtd_theme'
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'navigation_depth': -1,
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -186,9 +188,6 @@ texinfo_documents = [
      'Miscellaneous'),
 ]
 
-
-
-
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}
 

docs/conf.py

@@ -182,9 +182,6 @@ def setup(app):
      'Miscellaneous'),
 ]
 
-
-
-
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}
 

docs/nise/class.rst

@@ -712,9 +712,6 @@ wait_for_debounce
             :type maximum_time_ms: float in seconds or datetime.timedelta
 
 
-Properties
-==========
-
 
 .. contents:: Session