Merge pull request #2 from mjbear/aetest-loop-doc-improv

Update Testcase/TestScript words in loop.rst

Author: aitestino

docs/aetest/debugging.rst

@@ -227,8 +227,9 @@ want to pause the testscript execution somewhere & check the current state
 and/or configuration of your environment, logs, and testbed devices?
 
 The **pause on phrase** feature allows you to pause on **any** log messages
-generated by the current script run, without requiring any modifications to the
-scripts and/or its libraries. When enabled, it actively filters all log messages
+generated by the current script run, including CLI output from devices,
+without requiring any modifications to the scripts and/or its libraries.
+When enabled, it actively filters all log messages
 propagated to the ``logging.root`` logger, and pauses when a match is found.
 
 Three distinct types of pause actions are supported:
@@ -486,3 +487,46 @@ Below are some examples of the pause on phrase feature in action:
     #   -> /path/to/my/example/testscript.py[20] test()
     #   (press Ctrl-D to resume execution)
     #   >>>
+
+The pause will also dump the connection information, including which devices are currently connected.
+
+.. code-block:: python
+
+    # --------------------------------------------------------------------------------
+    # Pause On Phrase: Connection Information
+    #
+    # +-------------------+--------------------------------+
+    # |  Device Property  |             Value              |
+    # +-------------------+--------------------------------+
+    # |        Name       |           device.name          |
+    # |       Alias       |           device.alias         |
+    # | Active Connection |   alias of active connection   |
+    # |       Status      |     Connected|Disconnected     |
+    # |   Spawn Command   |  command for active connection |
+    # |      --------     |            --------            |
+    # |  Connection Alias |   connection alias e.g. cli    |
+    # |       Class       |  Unicon, Gnmi, Netconf, etc    |
+    # |         IP        |        IPV4|IPV6 address       |
+    # |      Protocol     |        ssh, telnet, etc        |
+    # |      --------     |            --------            |
+    # |        URL        |    <protocol>://<ip>:<port>    |
+    # +-------------------+--------------------------------+
+
+
+.. note::
+    
+    If it is required to connect to the device directly while the test is paused, the device connection must be disconnected
+    from before it can be accessed directly.
+
+.. code-block:: python
+
+    >>> import pyats.easypy as ep
+    >>> dev = ep.runtime.testbed.devices['<device>']
+    >>> dev.disconnect()
+
+    # the device can now be connected to in a separate terminal. Once ready to resume the test,
+    # break the connection and reattach with
+
+    >>> dev.connect()
+
+

docs/aetest/loop.rst

@@ -28,8 +28,8 @@ it with different parameters during each loop iteration.
 The following describes each section and their loop capability and behaviors:
 
 ``CommonSetup``/``CommonCleanup``
-    Common setup and cleanup sections are unique within each test script. They
-    are run only once per test script execution, and are not loopable.
+    Common setup and cleanup sections are unique within each TestScript. They
+    are run only once per TestScript execution, and are not loopable.
 
     ``subsection``
         Subsections within ``CommonSetup`` and ``CommonCleanup`` are loopable.
@@ -38,12 +38,12 @@ The following describes each section and their loop capability and behaviors:
 
 ``Testcase``
     Testcases are loopable. Each iteration of a looping ``Testcase`` is reported 
-    individually as new test case instances with a different ``uid``. When a 
+    individually as new ``Testcase`` instances with a different ``uid``. When a
     ``Testcase`` is looped, and all of its contents (setup, tests, and cleanup) are
     run fully per each iteration.
 
     ``setup``/``cleanup``
-        Setup and cleanup sections within each test case is unique, and are run
+        Setup and cleanup sections within each Testcase is unique, and are run
         only once per ``Testcase``. They cannot be looped individually, but
         if their parent ``Testcase`` is looped, then they are run once per
         ``Testcase`` iteration.
@@ -52,9 +52,9 @@ The following describes each section and their loop capability and behaviors:
         Test sections within ``Testcase`` are loopable individually. Each
         iteration has its own unique id and is reported as a new test 
         section. When a looping ``test`` section's parent ``Testcase`` is 
-        looped, the resulting loops are multiplicative. E.g.: if a test case is 
-        looped ``2x``and contains a test that is also looped ``2x``, that 
-        test would loop ``2x`` per test case loop iteration.
+        looped, the resulting loops are multiplicative. E.g.: if a Testcase is
+        looped ``2x`` and contains a test that is also looped ``2x``, that
+        test would loop ``2x`` per Testcase loop iteration.
 
 .. hint::
 
@@ -93,27 +93,27 @@ section object is then instantiated once for each iteration.
         def looped_subsection(self):
             pass
 
-    # Defining a test case that loops
+    # Defining a Testcase that loops
     # ----------------------------------
-    # This test case also contains a test section that is looped twice
+    # This Testcase also contains a test section that is looped twice
     @aetest.loop(uids=['testcase_one', 'testcase_two'])
     class Testcase(aetest.Testcase):
 
-        # Setup section of this test case is run once
-        # every time the test case is looped.
+        # Setup section of this Testcase is run once
+        # every time the Testcase is looped.
         @aetest.setup
         def setup(self):
             pass
 
         # Looped test section
-        # both iterations are run per test case iteration
+        # both iterations are run per Testcase iteration
         @aetest.loop(uids=['test_one', 'test_two'])
         @aetest.test
         def test(self):
             pass
 
-        # Cleanup section of this test case is run once
-        # every time the test case is looped.
+        # Cleanup section of this Testcase is run once
+        # every time the Testcase is looped.
         @aetest.cleanup
         def cleanup(self):
             pass
@@ -216,7 +216,7 @@ looped section is then driven to potentially do something different.
 
     from pyats import aetest
 
-    # Loop this test case with a loop parameter named "a"
+    # Loop this Testcase with a loop parameter named "a"
     # and set it to value 2 for the first iteration, 
     # and 3 for the second iteration
     @aetest.loop(a=[2, 3])
@@ -229,7 +229,7 @@ looped section is then driven to potentially do something different.
             # this test prints the exponential of two inputs, a and b
             print("%s ^ %s = %s" % (a, b, a**b))
 
-    # The output of the test case would look like this:
+    # The output of the Testcase would look like this:
     #   2 ^ 8 = 256
     #   2 ^ 9 = 512
     #   3 ^ 8 = 6561
@@ -449,7 +449,7 @@ would normally expect it to:
         def test_two(self, b):
             print('b = %s' % b)
 
-    # The output of the test case would be:
+    # The output of the Testcase would be:
     #   returning [1, 2, 3]
     #   a = 1
     #   a = 2
@@ -482,7 +482,7 @@ Dynamic Loop Marking
 --------------------
 
 So far, all loop examples focus on defining the ``@loop`` decorator directly within the 
-test scripts. E.g., the ``@loop`` decorators are coded as part of the test script. 
+TestScripts. E.g., the ``@loop`` decorators are coded as part of the TestScript.
 However, it is also possible to dynamically mark sections for looping during
 runtime, e.g., creating loops based on information that is only available during
 a script’s run. To do this, use the ``loop.mark()`` function.
@@ -506,7 +506,7 @@ a script’s run. To do this, use the ``loop.mark()`` function.
             aetest.loop.mark(self.simple_test, uids=['test_one', 'test_two'])
 
         # Note: the simple_test section is not directly marked for looping
-        # instead, during runtime, its testcase's setup section marks it for
+        # instead, during runtime, its Testcase's setup section marks it for
         # looping dynamically.
 
         @aetest.test
@@ -515,7 +515,7 @@ a script’s run. To do this, use the ``loop.mark()`` function.
             # by using the internal parameter "section"
             print("current section: %s" % section.uid)
 
-    # Output of this test case
+    # Output of this Testcase
     #   current section: test_one
     #   current section: test_two
     #
@@ -656,9 +656,9 @@ wish to customize loop behavior, it is possible to extend and override it.
 
     
     # This loop generator can be used as the @loop and loop.mark() argument.
-    # Let's define a looped test case with it.
+    # Let's define a looped Testcase with it.
 
-    # Looping this test case with a custom generator, and a=1, b=5
+    # Looping this Testcase with a custom generator, and a=1, b=5
     @aetest.loop(generator=DemoGenerator, a=1, b=5)
     class Testcase(aetest.Testcase):
 
@@ -668,7 +668,7 @@ wish to customize loop behavior, it is possible to extend and override it.
         def test(self, number):
             print('current number: %s' % number)
 
-    # Output of this test case
+    # Output of this Testcase
     #   current number: 1
     #   current number: 2
     #   current number: 3

docs/apidoc/easypy/pyats.easypy.runinfo.rst

@@ -22,14 +22,4 @@ Submodules
    :show-inheritance:
 
 
-.. automodule:: pyats.easypy.runinfo.kafka
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-
-.. automodule:: pyats.easypy.runinfo.s3
-   :members:
-   :undoc-members:
-   :show-inheritance:
 

docs/apidoc/index.rst

@@ -13,7 +13,6 @@ API Documentation
     robot/index
     async/index
     datastructures/index
-    tcl/index
     log/index
     reporter/index
     results/index

docs/apidoc/kleenex/index.rst

@@ -11,38 +11,39 @@ Subpackages
 
 .. toctree::
 
-   pyats.kleenex.loader
+   pyats.clean.loader
    pyats.kleenex.reporter
+   pyats.bringup
 
 Submodules
 ----------
 
 
-.. automodule:: pyats.kleenex.bases
+.. automodule:: pyats.bringup.bases
    :members:
    :undoc-members:
    :show-inheritance:
 
 
-.. automodule:: pyats.kleenex.bringup_base_cli_parser
+.. automodule:: pyats.bringup.base_cli_parser
    :members:
    :undoc-members:
    :show-inheritance:
 
 
-.. automodule:: pyats.kleenex.bringup_manager
+.. automodule:: pyats.bringup.manager
    :members:
    :undoc-members:
    :show-inheritance:
 
 
-.. automodule:: pyats.kleenex.bringup_manager_cli_parser
+.. automodule:: pyats.bringup.manager_cli_parser
    :members:
    :undoc-members:
    :show-inheritance:
 
 
-.. automodule:: pyats.kleenex.bringup_signals
+.. automodule:: pyats.bringup.signals
    :members:
    :undoc-members:
    :show-inheritance:
@@ -66,19 +67,19 @@ Submodules
    :show-inheritance:
 
 
-.. automodule:: pyats.kleenex.kleenex_traceback
+.. automodule:: pyats.clean.traceback
    :members:
    :undoc-members:
    :show-inheritance:
 
 
-.. automodule:: pyats.kleenex.schema
+.. automodule:: pyats.clean.schema
    :members:
    :undoc-members:
    :show-inheritance:
 
 
-.. automodule:: pyats.kleenex.utils
+.. automodule:: pyats.clean.utils
    :members:
    :undoc-members:
    :show-inheritance:

…/apidoc/kleenex/pyats.kleenex.loader.rst …cs/apidoc/kleenex/pyats.clean.loader.rstdocs/apidoc/kleenex/pyats.kleenex.loader.rst renamed to docs/apidoc/kleenex/pyats.clean.loader.rst docs/apidoc/kleenex/pyats.kleenex.loader.rst renamed to docs/apidoc/kleenex/pyats.clean.loader.rst

@@ -1,7 +1,7 @@
-pyats.kleenex.loader package
+pyats.clean.loader package
 ============================
 
-.. automodule:: pyats.kleenex.loader
+.. automodule:: pyats.clean.loader
    :members:
    :undoc-members:
    :show-inheritance:
@@ -10,7 +10,7 @@ Submodules
 ----------
 
 
-.. automodule:: pyats.kleenex.loader.markup
+.. automodule:: pyats.clean.loader.markup
    :members:
    :undoc-members:
    :show-inheritance:

docs/apidoc/kleenex/pyats.kleenex.reporter.rst

@@ -10,19 +10,7 @@ Submodules
 ----------
 
 
-.. automodule:: pyats.kleenex.reporter.base
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-
-.. automodule:: pyats.kleenex.reporter.clean
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-
-.. automodule:: pyats.kleenex.reporter.context
+.. automodule:: pyats.kleenex.reporter.reporter
    :members:
    :undoc-members:
    :show-inheritance:

docs/apidoc/log/index.rst

@@ -12,6 +12,7 @@ Subpackages
 .. toctree::
 
    pyats.log.commands
+   pyats.atslog
 
 Submodules
 ----------

docs/apidoc/log/pyats.log.commands.parser.rst

@@ -10,19 +10,19 @@ Submodules
 ----------
 
 
-.. automodule:: pyats.log.commands.parser.base
+.. automodule:: pyats.log.commands.parser.base_parser
    :members:
    :undoc-members:
    :show-inheritance:
 
 
-.. automodule:: pyats.log.commands.parser.xml
+.. automodule:: pyats.log.commands.parser.xml_parser
    :members:
    :undoc-members:
    :show-inheritance:
 
 
-.. automodule:: pyats.log.commands.parser.yaml
+.. automodule:: pyats.log.commands.parser.yaml_parser
    :members:
    :undoc-members:
    :show-inheritance: