rst docs
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 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 [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]
- (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 [edit section]
This is Issue 0046
To Do [edit section]
Here are the steps needed to convert the documentation to reStructuredText:
infrastructure/tools work [edit section]
- (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 [edit section]
- 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
- rst equivalent for [[Page Name]] (link to whole doc)
- See Markup_Mapping
- (started) determine list of pages to convert
- 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
- (started) determine syntax mapping from tbwiki markup to rst
- convert all tex pages to rst format
- update the page content in the process
Notes from first page set [edit section]
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 [edit section]
- (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 [edit section]
- 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?
- adding doc build to container build creates a dependency on sphynx
Fuego wiki Documentation conventions [edit section]
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 [edit section]
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 [edit section]
Other projects have documented their markup conventions. Here are a few for inspiration:
Resources [edit section]
- 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