All of your favourite documentation - in markdown format!
This is the easy bit, and is all that most people have to do. The following sections describe the format, structure and a few considerations necessary for correctly generating the desired output.
The documents are maintained in commonmark markdown format, with an .md extension.
Editing documents is as simple as editing a text file. Many IDEs have markdown support, including live previews. For Linux and Windows, ghostwriter is a nice option; it is free and supports side-by-side preview and custom stylesheets.
TIP
If you have the option to apply custom css to your markdown editor, set it to
./src/commonmark/en/resources/css/dhis2.cssto reflect the html output style for DHIS2!
The documents are structured as follows:
<root>
└── src
└── commonmark
└── en
├── dhis2_android_user_man_INDEX.md
├── dhis2_developer_manual_INDEX.md
├── dhis2_end_user_manual_INDEX.md
├── dhis2_implementation_guide_INDEX.md
├── dhis2_user_manual_en_INDEX.md
├── user_stories_book_INDEX.md
├── resources
│ ├── css
│ │ ├── dhis2.css
│ │ └── dhis2_pdf.css
│ └── images
│ └── dhis2-logo-rgb-negative.png
└── content
├── android
│ └── resources
│ └── images
├── common
│ └── bookinfo.yaml
├── developer
│ ├── resources
│ │ └── images
├── implementation
│ ├── resources
│ │ └── images
│ ├── `resources
│ │ └── images
├── stories
│ ├── resources
│ │ └── images
└── user
└── resources
└── images
The *_INDEX.md files are the starting points for the master documents. They contain only !INCLUDE directives.
e.g. dhis2_android_user_man_INDEX.md:
!INCLUDE "content/common/about-this-guide.md"
!INCLUDE "content/android/configure-dhis2-programs-to-work-on-android-apps.md"
!INCLUDE "content/android/android-event-capture-app.md"
!INCLUDE "content/android/android-aggregate-data-capture-app.md"
!INCLUDE "content/android/android-tracker-capture-app.md"
The !INCLUDE directives point to the "chapters" that are used to make up the manual.
NOTE
the
!INCLUDEdirectives are not part of pure commonmark format, but are used in pre-processing to build the master documents. The particular format here is the one supported by markdown-pp out of the box, but we could change it to another "include" format if desired.
It is perfectly valid to use !INCLUDE directives in the sub-documents too, but currently the documents are split up at chapter level only.
In addition to the !INCLUDE directives explained above, we now support !SUBMODULE directives.
The !SUBMODULE directives function the same way as !INCLUDE, but allow referencing another repository instead of a file below the path of the *_INDEX.md files.
The format of these directives is as follows:
!SUBMODULE "<repository>" "<branch>" "<path to chapter>"
<repository>(just the repository name - currently we only support repositories in https://github.com/dhis2/)<branch><path to chapter>(from the repository root)
e.g. using submodules, the equivalent to the above, for dhis2_android_user_man_INDEX.md, might be:
!INCLUDE "content/common/about-this-guide.md"
!SUBMODULE "dhis2-android-capture-app" "master" "docs/configure-dhis2-programs-to-work-on-android-apps.md"
!SUBMODULE "dhis2-android-capture-app" "master" "docs/android-event-capture-app.md"
!SUBMODULE "dhis2-android-capture-app" "master" "docs/android-aggregate-data-capture-app.md"
!SUBMODULE "dhis2-android-capture-app" "master" "docs/android-tracker-capture-app.md"
These !SUBMODULE directives would, in this example, point to the respective chapters inside a docs folder within the https://github.com/dhis2/dhis2-android-capture-app repository.
NOTE
These are not true git submodules, as they are simply cloned during the build process, and deleted on completion.
Image resources should be included inside a folder structure beginning with resources/images/ relative to the current document. e.g. for the chapter content/android/android-event-capture-app.md, the images are somewhere under content/android/resources/images/<rest-of-path>. The images will be collected under resources/images/content/android/<rest-of-path> relative to the master document, when the the files are pre-processed for generation.
If you want to control the alignment and size of images, you can take advantage of an extension of the pandoc processing tool that we use. It allows you to set attributes such as width, height and class in curly brackets at the end of the image definition. For example:
{ width=50% }
will make your image 50% of the page width (it is best to use percentages to support a variety of output forms), while
{ .center width=50% }
will also centre the image on the page (due to the definition of the .center class in css).
When images are written like
i.e. with caption text in the square brackets, they are rendered as figures with captions. These are centred by default, with a centred, italicised caption.
For screenshots of the DHIS 2 web interface, we recommend using Chrome browser, with the following two extensions:
- Window Resizer. Use this to set the resolution to 1440x900
- Fireshot. Use this to quickly create a snapshot of the visible part
Fireshot can even capture the full page, i.e. scrolled, if desired. It can also capture just a selected area (but the maximum width should always be 1440px)
When taking screenshots of the Android app, size should be set to 360x640.
In order to provide fixed references within the document, we can set a fixed text string to be applied to any section. For our markdown docs this is done by adding a comment after the section heading in the form:
<!-- DHIS2-SECTION-ID:name_of_section -->
where name_of_section is replace with the id you wish to use.
For example:
## Validation
<!--DHIS2-SECTION-ID:webapi_validation-->
To generate a data validation summary you can interact ...
Will set the section id of the level 2 heading Validation to "webapi_validation", which may then be referenced as "#webapi_validation" within the html file.
After the full html file is generated, it is post-processed and the first DHIS2-SECTION-ID after the start of the section is used as the section id.
Please follow the convention of lowercase letters and underscores, in order to create id's that are also valid as filenames when the html files are split.
As an extension to pure commonmark, we also support GFM tables (defined with pipes |), such as:
| Table Type | Description |
|:--|:----|
|Commonmark (HTML)| Tables described in pure HTML |
|Github Flavour Markdown (GFM)| Tables described with pipes: easier to read/edit, but limited in complexity|
which produces output like:
| Table Type | Description |
|---|---|
| Commonmark (HTML) | Tables described in pure HTML |
| Github Flavour Markdown (GFM) | Tables described with pipes: easier to read/edit, but limited in complexity |
For simple tables these are much more convenient for working with.
They are limited to single lines of text (i.e. each row must be on a single line), but you can, for example use <br> tags to create line breaks and effectively split up paragraphs within cells, if necessary.
You can also continue to use HTML tables when you really need more complexity (but you can also consider whether there is a better way of presenting the data).
In short, the correct form is "DHIS 2" when referring to the software system in normal written text. For convenience, some variables, paths, etc. use the compact form, and they should, of course, be respected in the documentation.
The documents are built in stages:
- The documents are pre-processed with markdown-pp. This assembles all the included (eventually nested) files into a single master document in a temporary directory. This includes copying and adjusting the links to included images.
- The final documentation (HTML and PDF formats) are generated with pandoc; using weasyprint as the PDF generation engine.
- The chunked html versions are generated by post-processing the full versions; splitting sections at h2 level, and inserting them into a template.
Weasyprint has several requirements that must be installed on the system:
sudo apt-get install build-essential python3-dev python3-pip python3-setuptools python3-wheel python3-cffi libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info unzip
brew install python3 cairo pango gdk-pixbuf libffi
brew install coreutils gnu-sed
Building on Windows 10 is achieved via the ubuntu app:
- Enable Windows Subsystem for Linux (WSL)
a. In the search bar, type “turn windows features on or off,” open the item.
b. A new window will pop up with a list of features with check boxes next to them. Scroll down to Windows Subsystem for Linux and check the box. This will install the necessary files, your computer will then restart, after which the installation is complete.
- Download Ubuntu from the Microsoft Store.
a. Open the Microsoft Store and search for Ubuntu.
b. Select one of the available apps (I tested this with Ubuntu 18.04 LTS)
Once the app is installed you can initialise it: start the app and set a ubuntu user name and password (these are independent from your Windows user). You should then update the packages:
sudo apt-get update
You can then continue as on native ubuntu:
sudo apt-get install build-essential python3-dev python3-pip python3-setuptools python3-wheel python3-cffi libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info unzip
NOTE
Microsoft warns against modifying files from both Windows itself and the Linux subsystem. If you wish to use Windows for checking out and editing the docs, note that the user directory on Windows is typically under
/mnt/c/Users/<windows-user>in the Ubuntu app. From there you can navigate to the checked-out repository and perform the build; Windows would then be used for the source, and Linux for the output. Alternatively, you can do everything in the Ubuntu app!
- run the build.sh script:
./build.sh
NOTE
The first time it is run, the build script will create a python virtual env and install the dependencies from the requirements.txt file. It will copy pandoc (v2.7.3), and install a "modified" version of markdown-pp; these are provided in the tools directory. The venv will then be activated to perform the rest of the build.
The generated files are placed in a target directory:
<root>
├── build.sh
├── README.md
├── requirements.txt
├── venv_setup
├── src
│ └── commonmark
│ └── en
│ .
│ .
│ .
├── target
│ └── commonmark
│ └── en
│ ├── android
│ │ ├── dhis2_android_user_man.pdf
│ │ └── html
│ ├── developer
│ │ ├── dhis2_developer_manual.pdf
│ │ └── html
│ ├── end-user
│ │ ├── dhis2_end_user_manual.pdf
│ │ └── html
│ ├── implementer
│ │ ├── dhis2_implementation_guide.pdf
│ │ └── html
│ ├── user
│ │ ├── dhis2_user_manual_en.pdf
│ │ └── html
│ └── user-stories
│ ├── html
│ └── user_stories_book.pdf
└── tools
├── linux
| └── pandoc.zip
├── mac
| └── pandoc.zip
└── python
└── markdown-pp-master
├── images
├── LICENSE
├── makefile
├── MANIFEST.in
├── MarkdownPP
├── readme.md
├── readme.mdpp
├── setup.py
└── test
As we transition to markdown, please bear in mind the following issues and shortcomings!
- It is not clear if we can continue the Bibliography support that Docbook provided (or if we need to)
- Chunked HTML output should use the same identifiers as the docbook output
- Intra- (and inter-) document links need updating to generate properly
- "Asides" (NOTE, TIP, WARNING, etc.) have classes applied in a post-processing step which doesn't apply to PDF output. (could be done as a pandoc filter instead).
- Section regarding documentation and Docbook needs rewrite (obviously)
- build environment needs improvement to allow easy generation on various platforms (but most developers will not need to build as they can see the expected output in a good markdown editor)
- in conjunction with previous point, the build script could be changed to a more robust build tool