Convert Fuego documentation to reStructuredText


 * Summary: Convert Fuego documentation to reStructuredText
 * Proposer: Tim Bird

Description
This task consist of 2 parts:

task 1 - convert the existing user guide PDF and online wiki documentation into reStructuredText, in the Fuego git repository, and integrate with readthedocs technology to replace the current documentation on the Fuego web site, and in the product itself. Tim can work on the web site integration with readthedocs. We will be switching over this fall from my personal bird.org web site to fuegotest.org.

task 2 - a second task is to validate the operation of Fuego using SeleniumHQ. Doing release testing on Fuego is a largely manual operation, and we should be able to test aspects of Fuego with itself, as a form of eating our own dog food. The idea here is to come up with scripts, based on the documentation, that can be used to verify that the descriptions and code fragments in the documentation work as documented.

In the long run adding the capability to do some driving of web interaction and comparing of screen shots will be very useful as general feature of the Fuego test framework.

This task is described by Fuego Issue 46: See: http://bird.org/fuego-1.2/Issue_0046

Related work

 * https://readthedocs.org
 * http://bird.org/tbwiki/TBWikiDocumentation

Scope
Phase 1 - 2 to 4 weeks? Phase 2 - 4 to 8 weeks?

These are wild guesses at this point.

Contractor Candidates
ProFusion (Gustavo Barbieri) is providing a bid for this work.

Comments
Bill Traynor suggested that we look at pandoc: https://pandoc.org/

tbwiki markdown (which is what the fuego wiki pages are in now) is very similar to MoinMoin markdown - which I would guess pandoc already supports. So it might be really easy to convert to reStructuredText (or we might be able to take an existing input module and make one for tbwiki markdown).

Gustavo wrote:

We did a project for Intel/ClearLinux that added testable-shell codeblocks to sphinx, I'm trying to get those released as opensource and if we get there, we can verify all shell code blocks in the system, testing them in a virtualmachine -- all integrated into sphinx, just new build target. More than that we also added one to document web interactions, eventually needed in these documentation, using SeleniumHQ - it will execute web interactions, compare screenshots, etc. This doubles its usefulness: validate tutorials so they are correct AND use tutorials as project test.