Include automatic and manual test documentation.

.gitignore

@@ -6,6 +6,7 @@ doc/blivet.devicelibs.rst
 doc/blivet.formats.rst
 doc/blivet.rst
 doc/modules.rst
+doc/tests*.rst
 doc/_build
 po/*.gmo
 po/*.po

doc/Makefile

@@ -43,11 +43,16 @@ help:
 
 clean:
 	-rm -rf $(BUILDDIR)/*
+	-rm -f $(addprefix ./, tests.*)
 
 apidoc:
+	-rm -f $(addprefix ./, tests.* modules.rst)
+	$(SPHINXAPIDOC) -o . ../tests/
+	-cp modules.rst tests.modules.rst
 	-rm $(addprefix ./, $(MODULE_NAMES))
 	$(SPHINXAPIDOC) -o . $(SOURCEDIR)
 
+
 html: apidoc
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo

doc/conf.py

@@ -25,7 +25,11 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', \
+                'sphinx.ext.coverage', 'sphinx.ext.inheritance_diagram', 'sphinx.ext.graphviz'
+            ]
+
+inheritance_graph_attrs = dict(rankdir="LR", size='""')
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/index.rst

@@ -13,6 +13,7 @@ Contents:
 
    intro
    modules
+   tests.modules
 
 Indices and tables
 ==================

doc/intro.rst

@@ -197,3 +197,5 @@ from which to allocate the partition::
     new_part = b.newPartition(start=2048, end=204802048, parents=[sdb])
 
 All the rest is the same as the previous partitioning example.
+
+.. include:: ../tests/README.rst

tests/README.rst

@@ -0,0 +1,59 @@
+Testing Blivet
+==============
+
+Note: The test suite documented here is available only from the git repository
+not as part of any installable packages.
+
+In order to execute blivet's test suite from inside the source directory execute
+the command::
+
+    make test
+
+Tests descending from :class:`~.imagebackedtestcase.ImageBackedTestCase` or
+:class:`~.loopbackedtestcase.LoopBackedTestCase` require root access on the
+system and will be skipped if you're running as non-root user.
+Tests descending from :class:`~.imagebackedtestcase.ImageBackedTestCase` will
+also be skipped if the environment variable JENKINS_HOME is not defined. If
+you'd like to execute them use the following commands (as root)::
+
+    # export JENKINS_HOME=`pwd`
+    # make test
+
+To execute the Pylint code analysis tool run::
+
+    make check
+
+Running Pylint doesn't require root privileges.
+
+It is also possible to generate test coverage reports using the Python coverage
+tool. To do that execute::
+
+    make coverage
+
+It is also possible to check all external links in the documentation for
+integrity. To do this::
+
+    cd doc/
+    make linkcheck
+
+Test Suite Architecture
+------------------------
+
+Blivet's test suite relies on the base classes shown below. These classes
+take care of working with fake block or loop devices.
+
+.. inheritance-diagram::
+    tests.imagebackedtestcase
+    tests.loopbackedtestcase
+    tests.storagetestcase
+    tests.devicetree_test.BlivetResetTestCase
+
+Actual test cases inherit either :class:`unittest.TestCase` or one of
+these base classes. Some use cases require more levels of abstraction
+which is shown on the following diagram.
+
+.. inheritance-diagram::
+    tests.devicetree_test
+    tests.formats_test.fs_test
+    tests.formats_test.fslabeling
+