{{TableOfContents}}
= Introduction =
This page describes a change to the Fuego documentation system,
to convert from tex and tbwiki markup to rst (reStructuredText)

The current PDF documentation is built using tex source and pdflatex.
This documentation is stale, and not 

The current online documentation consists of wiki pages at:
http://fuegotest.org/wiki/Documentation. These pages are in 
tbwiki markup syntax, which is similar to MediaWiki format and
other wiki markdown formats, with some variations.

Problems [edit section]

== Problems ==
The tex documentation is out of date, hard to manage, and the resulting
PDF doesn't look very nice.  Also, the tex documentation is not browsable
on the web.

The tbwiki markup documentation is more comprehensive, and up-to-date,
and is available online.  However, the markup pages don't look like a nice
standalone set of docs. They exist alongside non-end-user-documentation 
pages in the wiki, which can lead to confusion. And they are not
under source code management control.

Proposal [edit section]

== Proposal ==
This "rst docs" proposal is for a system that uses rst (reStructuredText)
pages in the fuego source code repository, that can be built locally
using sphynx, and can be built automatically for online use using http://readthedocs.io/

It is desired to combine the two forms of documentation, while preserving
existing features and adding some new ones.

Desired features [edit section]

= Desired features =
 * documentation resides in the source repository (can be managed by git)
 * documentation is available as PDF
 * documentation is available as HTML
 * documentation is available on the web
 * documentation is available via Jenkins UI
 * documentation looks nice
 * documentation uses a widely known and supported markup language
 * documentation for the test API is auto-generated from source comments
 * documentation is easy to keep up-to-date
 * documentation can be translated

(''Note: this proposal does not address all of these features directly'')

To Do [edit section]

= To Do =
Here are the steps needed to convert the documentation to reStructuredText:
 * (done) add sphynx skeleton to git repository
 * convert all tbwiki pages to rst format
   * (started) determine syntax mapping from tbwiki markup to rst
     * See [[MarkupMapping]]
   * automated the conversion??
   * determine full list of pages to convert
   * decide how to organize content
   * actually convert all the pages
 * convert all tex pages to rst format
   * update the pages in the process
 * build documentation locally using sphynx
 * (done) create fuegotest account at readthedocs.io
 * register docs for fuegotest at readthedocs.io
 * put a link from fuegotest.org web site, and wiki to fuegotest.readthedocs.io
 * deprecate the wiki pages (remove top links??)
 * correlate the Jenkins interface with the PDF output (or html output)