[master 1/1] Include automatic and manual test documentation.
mulkieran
installerbot-noreply at redhat.com
Tue Jun 2 16:53:34 UTC 2015
From: Alexander Todorov <atodorov at redhat.com>
* No longer explicitly remove files in apidoc target, all handled in clean.
* Put autogenerated .rst files in subdirectories and gitignore them.
* Create a hidden file which includes some inheritance diagrams.
* Add commented out option for inheritance graph in conf.py.
* Include documentation for test modules at top level.
* Include documentation about testing in the introduction.
* Get rid of unnecessary MODULE_NAMES variable.
Signed-off-by: mulhern <amulhern at redhat.com>
---
.gitignore | 6 ++---
doc/Makefile | 8 +++---
doc/_inheritance.rst | 28 +++++++++++++++++++++
doc/conf.py | 3 +++
doc/index.rst | 3 ++-
doc/intro.rst | 2 ++
tests/README.rst | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++
7 files changed, 113 insertions(+), 8 deletions(-)
create mode 100644 doc/_inheritance.rst
create mode 100644 tests/README.rst
diff --git a/.gitignore b/.gitignore
index 54c7439..c18e3cc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,10 +2,8 @@
.*.swp
blivet*.tar.gz
blivet*.tar.bz2
-doc/blivet.devicelibs.rst
-doc/blivet.formats.rst
-doc/blivet.rst
-doc/modules.rst
+doc/blivet
+doc/tests
doc/_build
po/*.gmo
po/*.po
diff --git a/doc/Makefile b/doc/Makefile
index 2fc38ee..c58e5e6 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -8,7 +8,7 @@ SPHINXAPIDOC = sphinx-apidoc
PAPER =
BUILDDIR = _build
SOURCEDIR = ../blivet
-MODULE_NAMES = blivet.rst blivet.devicelibs.rst blivet.formats.rst modules.rst
+TESTDIR = ../tests
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
@@ -43,10 +43,12 @@ help:
clean:
-rm -rf $(BUILDDIR)/*
+ -rm -rf ./tests
+ -rm -rf ./blivet
apidoc:
- -rm $(addprefix ./, $(MODULE_NAMES))
- $(SPHINXAPIDOC) -o . $(SOURCEDIR)
+ $(SPHINXAPIDOC) -o ./tests $(TESTDIR)
+ $(SPHINXAPIDOC) -o ./blivet $(SOURCEDIR)
html: apidoc
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
diff --git a/doc/_inheritance.rst b/doc/_inheritance.rst
new file mode 100644
index 0000000..3a5ed45
--- /dev/null
+++ b/doc/_inheritance.rst
@@ -0,0 +1,28 @@
+Test Suite Inheritance Diagram
+------------------------------
+
+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
+
+Note: with :class:`sphinx.ext.inheritance_diagram` it is not possible to
+generate an inheritance diagram of all available classes. The ones shown above
+are considered a bit more important. If you want to see the inheritance diagram
+for other classes add the following markup to this document and rebuild it::
+
+ .. inheritance-diagram::
+ tests.module_name.className
diff --git a/doc/conf.py b/doc/conf.py
index 88d0f7c..f4ce531 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -286,6 +286,9 @@
# Allow duplicate toc entries.
#epub_tocdup = True
+# -- Options for inheritance graphs --------------------------------------------
+
+#extensions.extend(('sphinx.ext.inheritance_diagram', 'sphinx.ext.graphviz'))
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'https://docs.python.org/2': None}
diff --git a/doc/index.rst b/doc/index.rst
index 5c32438..0fcd519 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -12,7 +12,8 @@ Contents:
:maxdepth: 4
intro
- modules
+ blivet/modules
+ tests/modules
Indices and tables
==================
diff --git a/doc/intro.rst b/doc/intro.rst
index 158fe05..2cdafa8 100644
--- a/doc/intro.rst
+++ b/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
diff --git a/tests/README.rst b/tests/README.rst
new file mode 100644
index 0000000..14215c2
--- /dev/null
+++ b/tests/README.rst
@@ -0,0 +1,71 @@
+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 but requires Python3 due to usage
+of pocket-lint.
+
+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 several base classes listed below. All test cases
+inherit from them.
+
+- :class:`unittest.TestCase` - the standard unit test class in Python.
+ Used for tests which don't touch disk space;
+
+
+- :class:`~tests.storagetestcase.StorageTestCase` - intended as a base class for
+ higher-level tests. Most of what it does is stub out operations that touch
+ disks. Currently it is only used in
+ :class:`~tests.action_test.DeviceActionTestCase`;
+
+
+- :class:`~tests.loopbackedtestcase.LoopBackedTestCase` and
+ :class:`~tests.imagebackedtestcase.ImageBackedTestCase` - both classes
+ represent actual storage space.
+ :class:`~tests.imagebackedtestcase.ImageBackedTestCase` uses the same stacks
+ as anaconda disk image installations. These mimic normal disks more closely
+ than using loop devices directly. Usually
+ :class:`~tests.loopbackedtestcase.LoopBackedTestCase` is used for stacks of
+ limited depth (eg: md array with two loop members) and
+ :class:`~tests.imagebackedtestcase.ImageBackedTestCase` for stacks of greater
+ or arbitrary depth.
+
+
+In order to get a high level view of how test classes inherit from each other
+you can generate an inheritance diagram::
+
+ PYTHONPATH=.:tests/ python3-pyreverse -p "Blivet_Tests" -o svg -SkAmy tests/
--
To view this commit on github, visit https://github.com/rhinstaller/blivet/commit/796b8797e011c53d00e2f1b1eb8a8c183c04ba88
More information about the anaconda-patches
mailing list