Merge pull request labgrid-project#882 from Bastian-Krause/bst/doctest

doc: test code/config snippets in docs

Author: Emantor

.github/workflows/unit-tests.yml

@@ -25,7 +25,7 @@ jobs:
           ${{ runner.os }}-pip-
     - name: Install system dependencies
       run: |
-        sudo apt-get install -yq libow-dev openssh-server openssh-client libsnappy-dev ncurses-term
+        sudo apt-get install -yq libow-dev openssh-server openssh-client libsnappy-dev ncurses-term graphviz
         sudo mkdir -p /var/cache/labgrid/runner && sudo chown runner /var/cache/labgrid/runner
     - name: Prepare local SSH
       run: |
@@ -58,6 +58,7 @@ jobs:
         rm man/*.[1-8]
         make -C man all
         git --no-pager diff --exit-code
+        make -C doc doctest
     - uses: codecov/codecov-action@v1
   docker:
     runs-on: ubuntu-latest

doc/conf.py

@@ -36,6 +36,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.doctest',
               'sphinx.ext.napoleon',
               'sphinx.ext.coverage',
               'sphinx.ext.viewcode',
@@ -202,3 +203,45 @@ def run_apidoc(app):
 
 def setup(app):
     app.connect('builder-inited', run_apidoc)
+    app.connect('doctree-read', write_literal_blocks)
+
+# -- Options for doctest --------------------------------------------------
+
+doctest_global_setup = '''
+import os
+import shutil
+from unittest.mock import Mock, patch
+
+doctest_dir = '.build/doctest'
+
+if not os.getcwd().endswith(doctest_dir):
+    os.chdir(doctest_dir)
+'''
+
+doctest_global_cleanup = '''
+if os.getcwd().endswith(doctest_dir):
+    os.chdir('../..')
+'''
+
+def write_literal_blocks(app, doctree):
+    """
+    Writes named literal blocks to a file with that respective name in the temporary doctest build
+    directory. This allows doctest to test code snippets referring to these files as-is.
+    """
+    blocks = doctree.traverse(
+        condition=lambda node: node.tagname == 'literal_block'
+    )
+
+    for block in blocks:
+        name = '_'.join(block['names'])
+
+        if not name:
+            continue
+
+        out_path = os.path.join(app.outdir, name)
+
+        if os.path.exists(out_path):
+            raise Exception(f'literal block name "{name}" used multiple times')
+
+        with open(out_path, 'w') as f:
+            f.write(block.astext())

doc/configuration.rst

@@ -2608,6 +2608,8 @@ Implements:
 Arguments:
   - None
 
+.. _conf-strategies:
+
 Strategies
 ----------
 
@@ -2623,19 +2625,44 @@ A BareboxStrategy has four states:
 - barebox
 - shell
 
+Here is an example environment config:
+
+.. code-block:: yaml
+   :name: barebox-env.yaml
 
-to transition to the shell state:
+   targets:
+     main:
+       resources:
+         RawSerialPort:
+           port: '/dev/ttyUSB0'
+       drivers:
+         ManualPowerDriver: {}
+         SerialDriver: {}
+         BareboxDriver: {}
+         ShellDriver:
+           prompt: 'root@\w+:[^ ]+ '
+           login_prompt: ' login: '
+           username: root
+         BareboxStrategy: {}
 
-::
+In order to use the BareboxStrategy via labgrid as a library and transition to
+the ``shell`` state:
+
+.. testsetup:: barebox-strategy
+
+   from labgrid.strategy import BareboxStrategy
+
+   BareboxStrategy.transition = Mock(return_value=None)
+
+.. doctest:: barebox-strategy
 
    >>> from labgrid import Environment
-   >>> e = Environment("local.yaml")
+   >>> e = Environment("barebox-env.yaml")
    >>> t = e.get_target("main")
    >>> s = t.get_driver("BareboxStrategy")
    >>> s.transition("shell")
 
-
-this command would transition from the bootloader into a Linux shell and
+This command would transition from the bootloader into a Linux shell and
 activate the ShellDriver.
 
 ShellStrategy
@@ -2646,19 +2673,42 @@ A ShellStrategy has three states:
 - off
 - shell
 
+Here is an example environment config:
+
+.. code-block:: yaml
+   :name: shell-env.yaml
+
+   targets:
+     main:
+       resources:
+         RawSerialPort:
+           port: '/dev/ttyUSB0'
+       drivers:
+         ManualPowerDriver: {}
+         SerialDriver: {}
+         ShellDriver:
+           prompt: 'root@\w+:[^ ]+ '
+           login_prompt: ' login: '
+           username: root
+         ShellStrategy: {}
+
+In order to use the ShellStrategy via labgrid as a library and transition to
+the ``shell`` state:
 
-to transition to the shell state:
+.. testsetup:: shell-strategy
 
-::
+   from labgrid.strategy import ShellStrategy
+
+   ShellStrategy.transition = Mock(return_value=None)
+
+.. doctest:: shell-strategy
 
    >>> from labgrid import Environment
-   >>> e = Environment("local.yaml")
+   >>> e = Environment("shell-env.yaml")
    >>> t = e.get_target("main")
    >>> s = t.get_driver("ShellStrategy")
-   >>> s.transition("shell")
 
-
-this command would transition directly into a Linux shell and
+This command would transition directly into a Linux shell and
 activate the ShellDriver.
 
 UBootStrategy
@@ -2670,65 +2720,108 @@ A UBootStrategy has four states:
 - uboot
 - shell
 
+Here is an example environment config:
+
+.. code-block:: yaml
+   :name: uboot-env.yaml
+
+   targets:
+     main:
+       resources:
+         RawSerialPort:
+           port: '/dev/ttyUSB0'
+       drivers:
+         ManualPowerDriver: {}
+         SerialDriver: {}
+         UBootDriver: {}
+         ShellDriver:
+           prompt: 'root@\w+:[^ ]+ '
+           login_prompt: ' login: '
+           username: root
+         UBootStrategy: {}
+
+In order to use the UBootStrategy via labgrid as a library and transition to
+the ``shell`` state:
+
+.. testsetup:: uboot-strategy
 
-to transition to the shell state:
+   from labgrid.strategy import UBootStrategy
 
-::
+   UBootStrategy.transition = Mock(return_value=None)
+
+.. doctest:: uboot-strategy
 
    >>> from labgrid import Environment
-   >>> e = Environment("local.yaml")
+   >>> e = Environment("uboot-env.yaml")
    >>> t = e.get_target("main")
    >>> s = t.get_driver("UBootStrategy")
    >>> s.transition("shell")
 
-
-this command would transition from the bootloader into a Linux shell and
+This command would transition from the bootloader into a Linux shell and
 activate the ShellDriver.
 
-DockerShellStrategy
-~~~~~~~~~~~~~~~~~~~
-A DockerShellStrategy has three states:
+DockerStrategy
+~~~~~~~~~~~~~~
+A DockerStrategy has three states:
 
 - unknown
-- off
-- shell
+- gone
+- accessible
 
+Here is an example environment config:
 
-To transition to the shell state:
+.. code-block:: yaml
+   :name: docker-env.yaml
+
+   targets:
+     main:
+       resources:
+         DockerDaemon:
+           docker_daemon_url: unix://var/run/docker.sock
+       drivers:
+         DockerDriver:
+           image_uri: "rastasheep/ubuntu-sshd:16.04"
+           container_name: "ubuntu-lg-example"
+           host_config: {"network_mode":"bridge"}
+           network_services: [{"port":22,"username":"root","password":"root"}]
+         DockerStrategy: {}
+
+In order to use the DockerStrategy via labgrid as a library and transition to
+the ``accessible`` state:
 
-::
+.. testsetup:: docker-strategy
+
+   from labgrid.strategy import DockerStrategy
+
+   DockerStrategy.transition = Mock(return_value=None)
+
+.. doctest:: docker-strategy
 
    >>> from labgrid import Environment
-   >>> e = Environment("local.yaml")
+   >>> e = Environment("docker-env.yaml")
    >>> t = e.get_target("main")
-   >>> s = t.get_driver("DockerShellStrategy")
-   >>> s.transition("shell")
-
+   >>> s = t.get_driver("DockerStrategy")
+   >>> s.transition("accessible")
 
 These commands would activate the docker driver which creates and starts
 a docker container. This will subsequently make `NetworkService`_ instance(s)
 available which can be used for e.g. SSH access.
 
-Note: Transitioning to the "off" state will make any `NetworkService`_
-instance(s) unresponsive - which may in turn invalidate SSH connection
-sharing. Therefore, during automated test suites, refrain from transitioning
-to the "off" state.
-
 Reporters
 ---------
 
 StepReporter
 ~~~~~~~~~~~~
 The StepReporter outputs individual labgrid steps to `STDOUT`.
 
-::
+.. doctest::
 
     >>> from labgrid import StepReporter
     >>> StepReporter.start()
 
 The Reporter can be stopped with a call to the stop function:
 
-::
+.. doctest::
 
     >>> from labgrid import StepReporter
     >>> StepReporter.stop()
@@ -2746,14 +2839,14 @@ ConsoleLoggingReporter
 The ConsoleLoggingReporter outputs read calls from the console transports into
 files. It takes the path as a parameter.
 
-::
+.. doctest::
 
     >>> from labgrid import ConsoleLoggingReporter
     >>> ConsoleLoggingReporter.start(".")
 
 The Reporter can be stopped with a call to the stop function:
 
-::
+.. doctest::
 
     >>> from labgrid import ConsoleLoggingReporter
     >>> ConsoleLoggingReporter.stop()