"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.