"Test documentation" is the name of a feature of Fuego that
is currently under development.

One problem that is common in working with tests produced outside
one's company is that it is difficult to know how to interpret their
results.  A test user might encounter tests which fail, and which they
then have to answer: "what does this test actually do?", "how should
its failure be interpreted?", "should this failure stop a release?".

Test users often have to answer these questions themselves, as there
is often inadequate documentation about a test or an individual testcase.
For example, many individual LTP testcase programs have
very limited information available about them.

The 'test documentation' system intends to address this, by providing
a way for test users to share information about tests.

Here's how it works.  The system consists of template files, which
can contain static information as well as dynamic information.  The dynamic
information is obtained by running ftc and generating results data that
is used in the documentation.

The purpose of this is to allow users to create .rst pages
for a test, testset, or testcase, and have the system
fill in dynamic information on the page, for use in reports
or in the user interface (jenkins).

Inside each test directory, there can be a 'docs' directory, where
test documentation resides.  The files are in 'fuego template' format,
which is a custom format similar to .rst.

A page generator is used to replace macros in the template file with
results from ftc.  This page generator outputs files in .rst (reStructuredText)
format, which can then be converted into html or pdfs, or combined
into larger documents, using Sphynx.

The page generator is called gen-page.py.  It reads an 'ftmp' file,
and replaces macros and puts the resulting '.rst' files into
/fuego-rw/docs.

The macros have the same format as reStructuredText directives.
       
The intended data flow is:
  * /fuego-core/engine/test/Functional.foo/docs/Functional.foo.ftmp => [gen-page.py] (replace fuego macros) ->
  * /fuego-rw/docs/Functional.foo.rst => sphynx (convert to html or latex) ->
  * /fuego-rw/docs/Functional.foo.html, or
  * /fuego-rw/docs/Functional.foo.tex -> (included in)
  * /fuego-rw/docs/batch-run-bbb-testplan_default-21.pdf
    
Currently, gen-page.py only generates stub content.  The intent
is to call ftc or other routines to create the needed content
to replace the requested macros in the file.