Difference between revisions of "Convert Fuego documentation to reStructuredText"

From eLinux.org
Jump to: navigation, search
(add page)
 
(add project proposal)
Line 3: Line 3:
  
 
== Description ==
 
== Description ==
A
+
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 ==
 
== Related work ==
Line 11: Line 33:
  
 
== Scope ==
 
== Scope ==
Describe the expected amount of work (in person-weeks, please)
+
Phase 1 - 2 to 4 weeks?
 +
Phase 2 - 4 to 8 weeks?
 +
 
 +
These are wild guesses at this point.
  
 
== Contractor Candidates ==
 
== Contractor Candidates ==
Line 17: Line 42:
  
 
== Comments ==
 
== Comments ==
(remove this line and leave this section blank in your submission)
+
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.
  
 
[[Category:Project proposals 2017]]
 
[[Category:Project proposals 2017]]

Revision as of 11:30, 15 September 2017

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

  • Add links to related open source projects or existing work
  • Add links to any other resources which might be helpful
    • (talks, articles, mail list messages, etc.)

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.