Contents: Introduction Problems Proposal Desired features To Do

Introduction [edit section]

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]

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]

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]

• 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]

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)