DOCUMENTATION_FW ()

Framework to create any project documentation or specification documents with Markdown and to publish them into the formats HTML, MS Word DOCX, PDF.

Key features:

• Use simple plain text files (Markdown), which you can organaize in as many files (one file per chapter or even per subchapter).

• Put all files under version controll (e.g. Git) or even centralized on a Git server or Git service (e.g. GitHub, GitLab) to work with your team on the documentation at the same time. Be able to do versioning and diffs.

• Use free or OSS tools (open source software), e.g. UMLet, Draw.io, yEd for diagramming.

• Standard publishing channel is static HTML page, which is interactive readable offline on any web browser (e.g. Firefox, Chrome, MS Edge) or as static webpage with a simple Web Server (e.g. Apache, Nginx).

• For additional needs following publishing channels are available too:

  • PDF

    Export HTML to PDF (inklusive all pictures, linking, table of contents, footnotes and formatting) with the help of the OSS tool wkhtmltopdf (https://wkhtmltopdf.org)

  • MS-Word DOCX

    Export Markdown to MS-Word DOCX (inklusive all pictures, linking, table of contents, footnotes and formatting) with the help of the OSS tool Pandoc (a universal document converter)

Intro

This document describes the needed steps about how to setup the environment for this documentation.

In the following we assume we will install and run the Documentation Creation Environment (DCE) on a MS Windows client machine (e.g. MS Windows 10 Prof.).

As all documentation will be written as Markdown in pure text files, it is strongly recommended to use a version controll system to track all changes and to be able doing diffs and go back to older versions of a file.

You can use git at least locally, with a local repository. You can exchange the local repository with your project mates directly.

TODO: example of git commands to share local repositories

Installation

We try to install everything into the local user envrionment:

%HOMEDRIVE%%HOMEPATH%\installations\

Example

C:\Users\MarcusTrommen\installations

The directory structure would look like this:

%HOMEDRIVE%%HOMEPATH%\installations\
├── drawio
├── java

Visual Studio Code

As a Markdown editor we use Visual Studio Code

We use the following extensions:

• Markdown Preview Enhanced, v0.6.8
• UMLet, v15.1.0
• Draw.io Integration, v1.6.6
• Python, v2023.12.0
• Todo Tree, v0.0.226

Python 3.x

You need an istallation of Python 3.x as all scripts for transforming all Markdown content into HTML pages and transform the diagrams into PNG files are written in Python.

Visit the Python homepage (www.python.org).

Download current release from Download link.

TODO: test local installation on Windows

Java

Visit the OpenJDK homepage (www.openjdk.org).

Download current release from Oracle's OpenJDK JDK binaries for Windows. Choose then the download link for the "ZIP archive for Windows / x64".

Extract the ZIP archive into the target folder %HOMEDRIVE%\%HOMEPATH%\installations\java.

Example:

%HOMEDRIVE%%HOMEPATH%\installations\
├── java
│   └── jdk-20.0.2
│       ├── ...
│       └── bin
│           ├── ...
│           └── java.exe

draw.io

Visit the draw.io homepage (www.drawio.com).

Download current release from GITHUB - jgraph / drawio-desktop. Choose the download link item "Windows No Installer".

Move then the downloaded exe file into the folder %HOMEDRIVE%\%HOMEPATH%\installations\drawio.

Example:

%HOMEDRIVE%%HOMEPATH%\installations\
├── drawio
│   └── draw.io-21.6.8-windows-no-installer.exe

Drawing diagrams with the

UMLet

Visit the UMLet homepage (www.umlet.com).

Download current release from UMLet download page. Choose the stand-alone download option.

Extract the downloaded ZIP archive completely into the folder %HOMEDRIVE%\%HOMEPATH%\installations\Umlet

Example:

%HOMEDRIVE%%HOMEPATH%\installations\
├── Umlet
│   ├── Umlet.exe
│   ├── umlet.jar
│   └── ...

WKTOPDF

This tool allows you to render HTML into PDF and various image formats from command line using the Qt WebKit rendering engine. This runs entirely "headless" and do not require any display or display service.

Visit the wkhtmltopdf homepage (https://wkhtmltopdf.org).

Download current release from Download a precompiled binary. Choose the Windows > 7z Archive, 64-bit download option and download the 7z archive "wkhtmltox-0.12.6-1.mxe-cross-win64.7z".

Extract the downloaded ZIP archive completely into the folder %HOMEDRIVE%\%HOMEPATH%\installations\wkhtmltox

Example:

%HOMEDRIVE%%HOMEPATH%\installations\
├── wkhtmltox
│   ├── bin
│   │   ├── wkhtmltopdf.exe
│   │   └── ...
│   └── include
│       └── wkhtmltox

TODO Marcus: create a Python or PowerShell script to transform the whole bunch of HTML files into PDF files.

Working example usage is:

%HOMEDRIVE%%HOMEPATH%\installations\wkhtmltox\bin\wkhtmltopdf.exe \
"%HOMEDRIVE%%HOMEPATH%/myProject/Documentation/_www/<FILENAME>.html" \
--enable-local-file-access  \
"%HOMEDRIVE%%HOMEPATH%/myProject/Documentation/_pdf/<FILENAME>.pdf"

A new path "_pdf" needs to get created too!

PENCIL Project

Easy GUI Prototyping Tool with Built-in Shape Collections for desktop/web UI, Android and iOS GUI.

Additional Shape collections are available at code.google.com/archive/../evoluspencil/.

Visit the PENCIL Project homepage (pencil.evolus.vn/).

Download current release from PENCIL Project download page. Choose the Windows Installer Package download option.

Run the intallation file (actually Pencil-3.1.1.ga.exe) as administrator and install the program completely into the folder %HOMEDRIVE%\%HOMEPATH%\installations\Pencil.

Example:

%HOMEDRIVE%%HOMEPATH%\installations\
├── Pencil
│   ├── Pencil.exe
│   └── ...

Unfortunately Pencil does not yet support a headless mode for exporting or transforming any drawings with file extension *.epgz into PNG files with the help of the CLI (command line interface). Therefore you need to export any drawings manually to PNG files.

If there are better tools for GUI Prototyping available, please let me know!

Documentation Project Tree Layout

Let us assume you have created in your user home directory on your Windows machine a subdirectory or even a more or less complex path for your project. We will call it "myProject".

Create into this project directory a subdirectory called "Documentation" for consolidating your project documentation.

%HOMEDRIVE%%HOMEPATH%\myProject\Documentation
├── _www ........ temporary, HTML output of documentation generator
├── _pdf ........ temporary, PDF output of documentation generator
├── content ..... here are all the Markdown and additional files located to 
│   │             build the documentation, 
│   │             e.g. screenshots, PDFs, Excel calculations, etc.
│   ├── any_markdown_N.md ... example
│   ├── screenshot.png ...... example
│   ├── datasheet.pdf ....... example
│   ├── gui_mockup.png ...... example
│   └── calculation.xlsx .... example
├── originals ... here are all diagramms which get exported to PNGs
│   ├── diagram.drawio ... example
│   ├── diagram.umlet ... example
│   └── diagram.epgz .... example
├── .gitattributes ............................ git configuration file
├── .gitignore ................................ git configuration file
├── config_exportPdfFromHtml_template.py ...... template for local configuration
│                                               for exporter script
├── config_exportPdfFromHtml.py ............... local configuration for 
│                                               exporter script
├── config_exportPngFromDiagram_template.py ... template for local configuration
│                                               for exporter script
├── config_exportPngFromDiagram.py ............ local configuration for 
│                                               exporter script
├── config_template.py ........................ template for local configuration
│                                               for doc generator script
├── config.py ................................. local configuration for 
│                                               doc generator script
├── documentSequence.json ..................... File in JSON format.
│                                               Holds a list of filenames with
│                                               markdown content, but without
│                                               any filename extention.
│                                               It lists the sequence of markdown
│                                               files in which the documentations 
│                                               needs to get build to.
├── exportPdfFromHtml.py ...................... Python exporter script for 
│                                               PDF files
├── exportPngFromDiagram.py ................... Python exporter script for 
│                                               diagrams
├── main.py ................................... Python doc generator script
├── page.css .................................. stylesheet for viewing documentation
├── page_template.html ........................ HTML template for document generator
├── print.css ................................. stylesheet for print layout of 
│                                               documentation
├── README.md ................................. this file
└── requirements.txt .......................... Python requirements for 
                                                additional libs

To succeed this easily, create the subdirectories with the following MS-Windows command shell commands:

mkdir content
mkdir originals

Then stay in the MS-Windows command shell or Git-Bash shell and initialize the Git source code versioning with the command

git init

Create a file in the root directory of the project, named .gitignore with the following content:

# Python project cache directory
__pycache__
__pycache__/**

# project build directory
_www
_www/**

# locally adopted config file from config_template.py
config.py

# locally adopted config file from config_exportPngFromDiagram_template.py
config_exportPngFromDiagram.py

Create a file in the root directory of the project, named .gitattributes with the following content:

# Set the default behavior, in case people don't have core.autocrlf set.
* text=auto

# Explicitly declare text files you want to always be normalized and converted
# to native line endings on checkout.
*.md text
*.py text
*.css text
*.html text

# Declare files that will always have CRLF line endings on checkout.
#*.sln text eol=crlf

# Denote all files that are truly binary and should not be modified.
*.png binary
*.jpg binary
*.xlsx binary
*.docx binary

Now you can start with your project's documentation by just concentrating on the content, without formatting issues!

Just frequently run on the MS-Windows command shell the command:

python ./main.py

The "documentation generator" creates a subdirectory called _www where you will find an index.html. Open this index.html in your web-browser of choice (recommended is Google Chrome) to browse the current state of your documentation.

You can print an optimized version as PDF right throughout the web-browser. By the help of media links there is a print.css available. This CSS eliminates all elements which are not relevant for printing (e.g. headers and footers) and simplifies the layout, as it is optimized for viewing with mobile first in mind.

Do not forget to commit frequently into your Git version controll!

Have a good luck!

-Cheers, Marcus