dockertest.environment: Add support for INI config parser

this parser automatically gathers info from INI files about the subtest
configuration and prints it into the subtest documentation.

It requires #: prefix to store the value as description of following
configuration option.

Signed-off-by: Lukáš Doktor <ldoktor@redhat.com>
config_defaults: Use **string** to emphasize action required

Use **text** to emphasize description of variables, which need to be
changed before using the test.

Signed-off-by: Lukáš Doktor <ldoktor@redhat.com>
Add independent documentation module

*  Avoid playing games with docutils module w/in environment module.
   Make dedicated module for documentation rendering.
*  Break down classes further into a more managable tree w/ defined
   extension points.
*  Update all docstrings, add many more comments.
*  Update unittests
*  Updated Makefile to use new module + classes
*  Updated run_checkdocs.py to use new module + classes

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Strip config. section from all docstrings

*  Some empty-section removal
*  Some re-numbering of steps

Signed-off-by: Chris Evich <cevich@redhat.com>
dockertest.documentation: Integrate INI parser

*  Class and static method name changed, but interface
   and behavior same.  Update ConfigINIParser.__init__() to use
   SubtestDoc.module_filenames(root_path).
*  Removed unnecessary support for nested keys and hiding
   certain types of format-parsing errors.  Added unittests
   to verify some DocBase class methods & behavior.
*  Pull in default config. section docs by way of prefixing
   subtest list with documentation substitution key.

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Re-implement NoOverwriteDict as namedtuple

Provides similar benefits and instances will be
immutable.  Allows access to keys as if they were
attributes, generates it's own documentation.

The class-generator produces two methods with
private-names, though generated docs suggest
they are intended for subclass use.  Effectivly
renamed them with public names (``fields`` and
``asdict``)

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Port Sphinx's rst to text writer module

*  Originally part of the Sphinx source code,
   it provided a convenient starting place
   to allow our tooling to produce regular text output.

*  Moderatly modified original to not
   depend on any other Sphinx-specific resources
   or constructs.

*  Folded several unnecessary abstractions/globals
   into the one or two places that needed them,
   simplifying code.

*  Fixed many areas that were failing PEP8/Pylint
   checks.  There are some I could not fix without
   a ton of work, and others that are simply part
   of the docutils interface.  In these few cases
   I simply locally disabled the specifc warnings
   and added comments.

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs. Re-arrange general methods/classes up tree

*  The SummaryVisitor and various methods that use
   need to be relocated higher up the tree.  Future
   subclasses will need to make use of these as
   they provide generic format conversion facilities.

*  Add new doctree2text() method that makes use
   of previously added textwriter module and class.
   This method takes in RST and spits out nicely
   formatted text, for when html formatting is too
   rich and raw RST is too decorated.

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Unify ConfigINIParser expand parsing ability

*  Having a class heirarchy that combined both parsing
   and presentation didn't fit well with the multi-input
   and multi-output needs for this module.  There were also
   several missing parser aspects needed to fully support
   and validating the incoming ConfigParser format.  These
   were added as encountered, along with the guts of the
   original parsing logic.

*  Parsing aspects of BaseConfigDocs, SubtestConfigDocs,
   and SubSubtestConfigDocs integrated into ConfigINIParser
   which now subclasses the builtin tuple, to represent
   the parsed result as an ordered immutable collection
   of DocItem instances (also immutable).  This guarantees
   end-to-end read-only qualities while encapsulating
   the parsed data along with some limited access to
   it's source context.

*  Presentation aspects of the former class heirarchy will
   be reimplemented and integrated later into a configuration-
   documentation specific subclass based on DocBase in order
   to decouple it fully from any dependency on subtest module
   docstring parsing input or output.

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Move SummaryVisitor class below ConfigINIParser

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Disable */** magic warning for all of dockertest

*  In all cases it shouldn't be abused, however occasional
   use is fine when associated with appropriate safeguards.

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Implement ConfigDoc class to handle one section

*  Pass a single ini file through ConfigINIParser()
   and hold onto the result for rendering at a later
   time in some supported format.

*  When necessary, breaks down config docs into a
   general section and one section for each sub-subtest.
   Properly handles empty sections by not including them.

*  Doesn't impose any special-handling for DEFAULTS
   vs. subtest sections.  It's left up to the caller
   or subclasses if they are to be handled differently.

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Improve docstrings and base_path insensitivity

*  Several classes accept a default base_path as a
   parameter to begin search for things.  However,
   it will likely be necessary to alter this value,
   possibly for all relevant classes at once.

*  Dropped the unnecessary RSTDoc sub-class and
   moved that functionality into a render method
   on SubtestDoc.

*  Updated docstrings and comments to better clarify
   or correct information.

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Update SubtestDoc and SubtestDocs

*  Additional blank needed after the section
   heading of each subtest.

*  Allow class used for producing configuration
   documentation to be configurable at the class-level.

*  Allow the string used for when no configuration
   docs exist to be configurable at the class-level.
   When some recoverable problems occur in ConfigINIParser,
   replace the entire config section for that test with
   this message.

*  Remove the concept of config_cache since it's been
   replaced by ConfigINIParser instances, stored in
   an instance attribute.

*  Remove hard-coded special handling of DEFAULTS section
   out of SubtestDocs for processing separetly.  This
   free's it's presentation to be included anywhere
   within the main documentation file.

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Update Makefile to use new module/classes

*  Track code vs config. changes as independent
   dependencies for producing documentation.
   This greatly limits the amount of effort needed
   by Sphinx when performing successive builds
   with only small changes between each.

* Add the defaults section in as it's own include
  file, tracked separately from others.  Include
  the defaults section in the same docs section that
  introduces configuration formats and particulars.
  There's no reason this section needed to be tied
  onto the subtests documentation section.

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Re-implement most documentation unittests

*  Added much better coverage for the base-classes.

*  Fixed environment-dependency relating to CWD where
   tests happened to be executed from.

*  Independently verify docs. processing and rendering,
   separately from subtest docstring processing.

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Workaround python 2.7.3 regex bug

*  Older python doesn't support null-repeat non-greedy match
   properly, though it seems it's not entirely necessary anyway.

*  Also modified unittest data to potentially catch
   failed line-continuation parsing.

Signed-off-by: Chris Evich <cevich@redhat.com>
Travis: Always pip install python modules

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Rich-incorporation of defaults into subtest docs

*  Added a new class / singleton that tracks defaults from the first
   instantiation

*  Updated format strings & index.rst references so back-linking to
   defaults across files works properly

Signed-off-by: Chris Evich <cevich@redhat.com>
Docs: Add unittests, fix KeyErrors, formats and sub-subtest docs.

*  Added a handful of extra docstrings
*  Also a bunch of PEP8 cleanups here and in one test

Signed-off-by: Chris Evich <cevich@redhat.com>