Documentation HowTo

Building and maintaining the documentation

Requirements

  • Python (3.4+)
  • Graphviz to render the images.
  • Sphinx with ReadTheDocs theme
  • Preferably a Linux box with make
  • Calibre to create a .pdf from the .epub file

Setup

  1. Create a Python virtual environment python -m venv venv
  2. Activate the virtual environment source venv/bin/activate
  3. Upgrade pip: pip install --upgrade pip
  4. Install required Python packages into the virtual environment pip install sphinx sphinx_rtd_theme or use pip install -r requirements.txt

Building the documentation

  1. Build documentation make html

  2. Build .epub make epub

  3. Convert .epub to .pdf by using Calibre:

    ebook-convert FlowchartWiki.epub .pdf --paper-size 'a4' --pdf-page-numbers --margin-bottom 30 --margin-left 60 --margin-top 30 --margin-right 30
    

Extraction of original source documents

The original source documentation was in a FlowchartWiki based MediaWiki installation.

Most of the pages have been extracted in two formats:

  • MediaWiki markup, extracted by manually copying the markup from the “edit page” option.
  • .html markup extracted by using wget "http://www.flowchartwiki.org/wiki/index.php?title=Main_Page&action=render" -O Main_Page.html

(These files have been retained in the source/original folder.)

The .html file was then converted to restructuredText by using pandoc:

pandoc -f html -t rst main.html -o main.rst

Finally the .rst file was manually updated and polished.