Add API docs chapter, document RandomDirectoryContext

Author: bittner

cli_test_helpers/decorators.py

@@ -14,6 +14,10 @@
 class ArgvContext:
     """
     A simple context manager allowing to temporarily override ``sys.argv``.
+
+    Use it to mimic the command line arguments of the CLI application.
+    Note that the first argument (index ``0``) is always the script or
+    application name.
     """
 
     def __init__(self, *new_args):
@@ -57,6 +61,12 @@ def __enter__(self):
 class RandomDirectoryContext(TemporaryDirectory):
     """
     Change the execution directory to a random location, temporarily.
+
+    Keyword arguments are optional and identical to the ones of
+    `tempfile.TemporaryDirectory`_ of the Python standard library.
+
+    .. _tempfile.TemporaryDirectory:
+        https://docs.python.org/3/library/tempfile.html#tempfile.TemporaryDirectory
     """
 
     def __enter__(self):

docs/api.rst

@@ -0,0 +1,21 @@
+API Documentation
+=================
+
+This section describes the context managers and helper functions provided
+by the CLI test helpers package.
+
+.. module:: cli_test_helpers
+
+Context Managers
+----------------
+
+.. autoclass:: ArgvContext
+
+.. autoclass:: EnvironContext
+
+.. autoclass:: RandomDirectoryContext
+
+Utilities
+---------
+
+.. autofunction:: shell

docs/conf.py

@@ -10,9 +10,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
 
 
 # -- Project information -----------------------------------------------------
@@ -28,6 +28,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autodoc',
     'sphinx.ext.extlinks',
     'sphinx.ext.viewcode',
 ]

docs/index.rst

@@ -9,6 +9,7 @@ Contents
 
    installation
    tutorial
+   api
    other
    techniques
    contributing

docs/tutorial.rst

@@ -36,8 +36,8 @@ Start with a simple set of functional tests:
   installed)
 - Is command XYZ available? etc. Cover your entire CLI usage here!
 
-This is almost a stupid exercise: Run the command as a shell command
-and inspect the exit code of the exiting process, e.g.
+This is almost a stupid exercise: Run the command as a :func:`~cli_test_helpers.shell`
+command and inspect the exit code of the exiting process, e.g.
 
 .. code-block:: python
 
@@ -67,7 +67,8 @@ Then you're ready to take advantage of our helpers.
 ``ArgvContext``
 +++++++++++++++
 
-``ArgvContext`` allows you to mimic the use of specific CLI arguments:
+:class:`~cli_test_helpers.ArgvContext` allows you to mimic the use of
+specific CLI arguments:
 
 .. code-block:: python
 
@@ -96,8 +97,8 @@ See more |example code (argparse-cli)|_.
 ``EnvironContext``
 ++++++++++++++++++
 
-``EnvironContext`` allows you to mimic the presence (or absence) of
-environment variables:
+:class:`~cli_test_helpers.EnvironContext` allows you to mimic the presence
+(or absence) of environment variables:
 
 .. code-block:: python
 
@@ -112,6 +113,20 @@ environment variables:
 
 See more |example code (click-command)|_.
 
+``RandomDirectoryContext``
+++++++++++++++++++++++++++
+
+:class:`~cli_test_helpers.RandomDirectoryContext` allows you to verify that
+your CLI program logic is independent of where it is executed in the file
+system:
+
+.. code-block:: python
+
+    def test_load_configfile():
+        """Must not fail when executed anywhere in the filesystem."""
+        with ArgvContext('foobar', 'load'), RandomDirectoryContext():
+            foobar.cli.main()
+
 
 .. |example code (argparse-cli)| replace:: example code
 .. |example code (click-cli)| replace:: example code