{{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 has not been kept up-to-date.

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 ==
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 ==
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 =
 * (done) documentation resides in the source repository (can be managed by git)
 * (done) documentation is available as PDF
 * (done) documentation is available as HTML
 * (done) documentation is available on the web
 * documentation is available via Jenkins UI
 * (done) documentation looks nice
 * (done) 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'')

== Issue number ==
This is [[Issue 0046]]


= To Do =
Here are the steps needed to convert the documentation to reStructuredText:

== infrastructure/tools work ==
 * (done) add sphynx skeleton to git repository
 * (done) document how to build the docs
   * (done) with a page on building documentation - see [[Building Documentation]]

== conversion work ==
 * convert desired tbwiki pages to rst format
   * (started) determine syntax mapping from tbwiki markup to rst
     * See [[Markup_Mapping]]
       * rst equivalent for [''''''[Page Name]''''''] (link to whole doc)
         * may have to convert to link to top section of doc and add top sections where they are missing
   * (started) determine list of pages to convert
     * See [[rst page conversion list]]
   * decide how to organize content
     * is it too much to reorganize the material while converting the format (yes)
   * write tools to automate the conversion??
   * actually convert all the pages
   * put the pages in the fuego/docs directory
     * one is already there: https://bitbucket.org/fuegotest/fuego/src/master/docs/rst_src/Quickstart_Guide.rst

 * convert all tex pages to rst format
   * update the page content in the process

=== Notes from first page set ===
Based on files received week of 8/24:
 - would like to word-wrap all files at 80 columns
   - architecture.rst has some long lines in the 'jenkins' section
 - why are the pages renamed?
   - why not keep wiki page name?
 - where is "images"?
   - did you just copy these from the wiki (it seems so)
   - I put these into the fuego directory
 - on my system, the theme is Alabaster 0.7.7, which looks pretty good
   and has a search function
 - architecture.rst
   - item inside YellowBox in wiki is inside a grey box in html doc
   - not sure I care

 in my build:
   - added architecture.rst and images to fuego repository (master branch)
   - moved rst files to rst_src
   - can make html and latexpdf

 in html files:
   - Too many top-level headings (in architecture.rst)

 - didn't have time for more review (of other files)
 - should discuss/decide overall page organization
 - try to eliminate any warnings





== readthedocs work ==
 * (done) create fuegotest account at readthedocs.io
 * (done) register docs for fuegotest at readthedocs.io
 * (done) put a link from fuegotest.org web site, and wiki to fuegotest.readthedocs.io


== cleanup and correlation ==
 * deprecate the wiki pages (remove top links??)
 * correlate the Jenkins interface with the PDF output (or html output)
 * include html and/or PDF documentation in container
   * adding doc build to container build creates a dependency on sphynx
     * if sphinx not found, copy materials from readtheddocs.io?



= Fuego wiki Documentation conventions =
This section describes desired conventions for the conversion of 
pages in tbwiki markup to rst markup, for the rst docs conversion project.

Also, this section documents preferences for which rst markup syntax
should be used for Fuego documentation elements, going forward as
the documentation is enhanced and maintained.

== some guidelines ==
This section is not yet organized, but here is a list of guidelines.

 * filenames should be marked with double-accents `''''''`
 * whitespace should be removed from line ends and end of files
   * tbwiki introduced lots of extra newlines
 * when converting numbered lists, remove leading bullets
   * tbwiki did not support numbered lists (so bullets were used), but rst does
 * keep line length to 72 columns, where possible
   * exceptions are allowed, but should be rare
 * convert tbwiki NOTES to rst .. note:: syntax
 * Heading conventions:
   * Page heading (h1)- top and bottom ###############
   * level 1 section heading (h2) - top and bottom =============
   * level 2 section heading (h3) - bottom ============
   * level 3 section heading (h4) - bottom ------------
   * level 4 section heading (h5) - bottom ````````````
 

 * remove 'Fuego_' prefix from filename (of wiki page)
 * use 2 spaces (and no tabs) to indent literal blocks
 * in bullet lists that are sets of instructions or steps, usually the first
   word of each step should be capitalized
 * literal blocks should normally have blank lines before and after them, to
   set them off from the rest of the text.
 * convert %%%% on wiki page to % in rst page
 * capitalize Docker and Jenkins when they are used to describe the Docker system or the Jenkins system (but not for directory or user names)










== examples ==
Other projects have documented their markup conventions.  Here are a few
for inspiration:
 * https://docs.openstack.org/doc-contrib-guide/rst-conv.html




= Resources =
 * rst Syntax cheat sheet: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#id4
 * rst basic overview: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 * see [[Markup Mapping]]