DHIS 2 Documentation Guide¶

DHIS 2 Documentation System Overview¶

DHIS 2 is a web-based information management system under very active development with typically two major releases per year. Each release typically includes a number of new features and additional functionality. Given the fast pace of development, the system's wide user base and distributed, global nature of development, a comprehensive documentation system is required.

In this chapter, we will describe the documentation system of DHIS 2 and how you can contribute.

Introduction¶

The DHIS 2 documentation is written in Commonmark markdown format. One of the main advantages of markdown is that there is complete separation between the content and presentation. Commonmark is a strongly defined, highly compatible specification of markdown. Since markdown can be transformed into a wide variety of formats (HTML, PDF, etc) and is a text-based format, it serves as an ideal format for documentation of the system.

There exist a wide range of text editors which can be used for the creation of markdown files. For Linux and Windows, ghostwriter is a nice option; it is free and supports side-by-side preview and custom style sheets.

One of the key concepts to keep in mind when authoring documentation in markdown, or other presentation neutral formats, is that the content of the document should be considered first. The presentation of the document will take place in a separate transformation step, whereby the source text will be rendered into different formats, such as HTML and PDF. It is therefore important that the document is well organised and structured, with appropriate tags and structural elements being considered.

It is good practice to break your document in to various sections using the section headings. In this way, very complex chapters can be split into smaller, more manageable pieces. This concept is essentially the same as Microsoft Word or other word processing programs. The rendering process will automatically take care of numbering the sections for you when the document is produced.

Getting started with GitHub¶

The DHIS 2 documentation system is managed at GitHub across a variety of source code repositories. GitHub is a platform that enables multiple people to work on software projects collaboratively. In order for this to be possible, a version control system is necessary to manage all the changes that multiple users may make. GitHub uses the git source control system. While it is beyond the scope of this document to describe the functionality of git, users who wish to create documentation will need to gain at least a basic understanding of how the system works. A basic guide is provided in the next section. The reader is referred to the git manual for further information.

In order to start adding or editing the documentation, you should first perform a checkout of the source code. If you do not already have a GitHub account, you will need to get one. This can be done here. Once you register with GitHub, you will need to request access to the dhis2-documenters group if you wish to modify the source code of the documentation directly. However, anyone can clone the documentation into their own repository, commit the changes to that fork, and request that the changes be merged with the source of the documentation with a pull request to the parent repository.

The structure of the documentation site is defined in the build repository dhis2-docs-builder. If you wish to add new parts to the structure, changes will have to be made there; this is usually only relevant to the internal DHIS2 team.

Tip

The best way to find the source of the document you wish to edit is to find the document on the docs.dhis2.org website and click the "Edit" icon at the top of the page.

Getting the document source¶

In order to edit the documentation, you will need to download the source of the documentation to your computer. GitHub uses a version control system known as git . There are different methods for getting Git working on your system, depending on which operating system you are using. A good step-by-step guide for Microsoft operating systems can be viewed here. Alternatively, if you are comfortable using the command line, you can download git from this page If you are using Linux, you will need to install git on your system through your package manager, or from source code. A very thorough reference for how git is used is available in a number of different formats here.

Once you have installed git on your system, you will need to download the document source. Just follow this procedure:

1. Make sure you have git installed.

2. On Windows systems, visit the relevant repository URL and press "Clone in Desktop". If you are using the command line, just type git clone git@github.com:dhis2/dhis2-docs.git (note that in this example dhis2 is owner of the repository and dhis2-docs is the name of the repository)

3. The download process should start and all the documentation source files will be downloaded to the folder that you specified.

4. Once you have the source, be sure to create your own branch for editing. Simply executegit checkout -b mybranch where mybranch is the name of the branch you wish to create.

Editing the documentation¶

When writing or editing documentation, there are a few key project-specific conventions that you should be aware of, which are outlined in this section. In addition, several markdown extensions are implemented and are demonstrated for convenience in the Markdown support and extensions later in this document.

Using images¶

Image resources should be included as relative paths inside a sub-folder 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> and are referenced like ![](resources/images/<rest-of-path>)

Styling images¶

If you want to control the alignment and size of images, you can take advantage of a markdown extensionthat 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:

![](resources/images/maintainence/predictor_sequential.png){ width=50% }

![](resources/images/maintainence/predictor_sequential.png){ .center width=50% }

When images are written like

![Approving and accepting](resources/images/data_approval/approval_level_steps.png)

Taking screenshots¶

For screenshots of the DHIS 2 web interface, we recommend using Chrome browser, with the following two extensions: 1. Window Resizer. Use this to set the resolution to 1440x900 2. 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.

Localising images¶

Localisation of images is supported by storing language-specific versions of an image alongside the original image. The filename should be the same as the original English version, but should include _ plus the language code at the end of the name, before the extension.

For example, if you want to have a French version of
resources/images/my_screenshot.png
You can simply create the French version and save it as
resources/images/my_screenshot_fr.png

The link in the documention should still point at the original image. When the documentation site is built for each language, localised images will be identified and used instead of the English originals.

The language code is the first part of the URL that you see after the "docs.dhis2.org/" when viewing the localised version of the documentation. At the time of writing, for example, we have fr, es_419, pt, cs and zh.

Section references¶

In order to provide fixed references (anchors) within the documentation, we can set a fixed text string to be applied to any section. For our markdown processor this is done by adding a hash id in curly brackets at the end of the line with the section title, e.g.

## Validation { #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" from any html file.

Note

In order to support linking by anchor reference from other documents, please try to keep the section ids unique. For example, if "#webapi_validation" is unique across the documentation, then you can refer to it from any other part of the documentation simply with [link name](#webapi_validation).
If the section id being referenced is not unique, the document processor will attempt to resolve to the "closest" anchor with that name. When the linking file belongs to a specific version, the processor will ignore anchors belonging to different versions.

Caution

Our documentation is compiled into both pages and full documents. For this reason it is not advised to include paths in inter-document references. Please use unique section ids as described above in order for the links to resolve correctly in both document types.

Please follow the convention of lowercase letters and underscores, in order to create id's that are also valid as filenames in cases where we split files as part of the document generation.

Tables¶

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:

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).

DHIS 2 Bibliography¶

Bilbliographic references are currently not supported in the markdown version of DHIS 2 documentation.

Handling multilingual documentation¶

The DHIS 2 documentation has been translated into a number of different languages including French, Spanish and Portuguese. If you would like to create a translation of the documentation or contribute to one of the existing translations, please contact the DHIS 2 documentation team at the email provided at the end of this chapter.

Committing your changes back to GitHub¶

Once you have finished editing your document, you will need to commit your changes back to GitHub. Open up a command prompt on Windows or a shell on Linux, and navigate to the folder where you have placed your documentation. If you have added any new files or folders to your local repository, you will need to add them to the source tree with the git add command, followed by the folder or file name(s) that you have added. Be sure to include a descriptive comment with your commit.

git commit -m "Improved documentation on organisation unit imports with CSV."

Finally, you should push the changes back to the repository with git push origin mybranch, where "mybranch" is the name of the branch which you created when you checked out the document source or which you happent o be working on. In order to do this, you will need the necessary permissions to commit to the repository.When you have committed your changes, you can issue a pull request to have them merged with the master branch. You changes will be reviewed by the core documentation team and tested to ensure they do not break the build, as well as reviwed for quality. As mentioned previously, you can also push your changes to your own GitHub repo, if you do not have access to the main repo, and submit a pull request for your changes to be merged.

If you have any questions, or cannot find that you can get started, just raise a question on our development community of practice.

Markdown support and extensions¶

This section attempts to capture the markdown and extensions that are supported for DHIS 2 documentation, and to provide a preview of the applied styles.

h3 Heading¶

h4 Heading¶

h5 Heading¶

h6 Heading¶

Body text.

Horizontal Rules¶

___

---

***

Emphasis¶

This is bold text

This is bold text

This is italic text

This is italic text

Strikethrough

Blockquotes¶

> Basic blockquote

> Blockquotes can also be nested...
>> ...by using additional greater-than signs right next to each other...
> > > ...or with spaces between arrows.

Note that nested blockquotes have a special style applie to help to indicate hierarchical structures.

> You can also manually apply the nested style to single blockquotes { .nested }

Code¶

Inline code

Inline highlighted code var test = 0; made within

`#!js var test = 0;`

Indented code

// Some comments
line 1 of code
line 2 of code
line 3 of code

Block code "fences"

Sample text here...

Syntax highlighting

var foo = function (bar) {
  return bar++;
};

console.log(foo(5));

Long lines

Buffalo buffalo (the animals called "buffalo" from the city of Buffalo) [that] Buffalo buffalo buffalo (that the animals from the city bully) buffalo Buffalo buffalo (are bullying these animals from that city).

Highlight specific lines

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

``` py hl_lines="2 3"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

Add a title

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

``` py hl_lines="2 3" title="bubble_sort.py"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

Lists¶

Unordered

• Create a list by starting a line with +, -, or *
• Sub-lists are made by indenting 2 spaces:

  • Marker character change forces new list start:

    • Ac tristique libero volutpat at

    • Facilisis in pretium nisl aliquet

      an indented code block
      

    • Nulla volutpat aliquam velit

    • Very easy!

Ordered

1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit

3. Integer molestie lorem at massa

4. You can use sequential numbers...

5. ...or keep all the numbers as 1.

Start numbering with offset?:

1. foo
2. bar

Multi-Levels

1. firstitem
2. still first level
   1. second level
   2. still second
      1. third level

         a block of code at the third level
         

      2. still third level
   3. second level again
3. back to the first level
   1. second
      1. Oh, do stop it!

Tables¶

Right aligned and centred columns

Links¶

link text

link with title

Autoconverted link https://github.com/dhis2

Images¶

Images are shown full size with a max-width of 100%

![](resources/images/dhis2_screenshots.jpg)

Adding a title automatically causes rendering as a figure. Inline classes and styles can be added in curly brackets.

![The Title](resources/images/dhis2_screenshots.jpg){ .center width=50% }

Youtube¶

Youtube videos can be embedded in a similar way to images. Simply provide the youtube embed link instead of an image file

![](https://www.youtube.com/embed/UqXSMaXBtD8)

Note

Be sure to use the "embed" youtube link!

As with images, adding a title will render the video as a figure

![DHIS2: Information for Action](https://www.youtube.com/embed/UqXSMaXBtD8)

Admonitions¶

The following admonitions are supported, with pre-defined styles, in addition to general blockquotes.

Note¶

> **Note**
>
> A note contains additional information which should be considered or a
> reference to more information which may be helpful.

Tip¶

> **Tip**
>
> A tip can be a useful piece of advice, such as how to perform a
> particular task more efficiently.

Important¶

> **Important**
>
> Important information should not be ignored, and usually indicates
> something which is required by the application.

Caution¶

> **Caution**
>
> Information contained in these sections should be carefully
> considered, and if not heeded, could result in unexpected results in
> analysis, performance, or functionality.

Warning¶

> **Warning**
>
> Information contained in these sections, if not heeded, could result
> in permanent data loss or affect the overall usability of the system.

Work in progress¶

> **Work In Progress**
>
> Information contained in these sections, will indicate that these are issues or errors we are currently working on.

Example¶

> **Example**
>
> A way to bring special attention to examples.
>
> Admonitions can include a code blocks
>
> ```js
> var foo = function (bar) {
>   return bar++;
> };
>
> console.log(foo(5));
> ```

Mathematical equations¶

MathJax provides support for displaying mathematical content in the browser with support for mathematical typesetting in different notations (e.g. LaTeX, MathML, AsciiMath).

Blocks must be enclosed in \[ ... \] or $$ ... $$ or \begin{} ... \end{} on separate lines.
Inline blocks must be enclosed in $...$ or \(...\).

\[
Indicator = {\frac{BcgVaccinationsUnder1Year}{TargetPopulationUnder1Year}} \times 100
\]

\[3 < 4\]

\begin{align}
    p(v_i=1|\mathbf{h}) & = \sigma\left(\sum_j w_{ij}h_j + b_i\right) \\
    p(h_j=1|\mathbf{v}) & = \sigma\left(\sum_i w_{ij}v_i + c_j\right)
\end{align}

The wave equation for \( u \) is

\begin{equation}
  \frac{\partial^2u}{\partial t^2} = c^2\nabla^2u
\end{equation}

where \( \nabla^2 \) is the spatial Laplacian and \( c \) is constant.

This equation $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$ is inline.

The homomorphism $f$ is injective if and only if its kernel is only the 
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such that $f(a)=f(b)$.

Typographic replacements¶

Subscript / Superscript¶

- 19^th^
- H~2~O

• 19^th
• H₂O

++Inserted text++

Marked text

Footnotes¶

Footnote 1 link¹.

Footnote 2 link².

Inline footnote^[Text of inline footnote] definition.

Duplicated footnote reference².

Definition lists¶

Term 1

Definition 1 with lazy continuation.

Term 2 with inline markup

Definition 2

{ some code, part of Definition 2 }

Third paragraph of definition 2.

Keys¶

Keys is an extension to make entering and styling keyboard key presses easier. Syntactically, Keys is built around the + symbol. A key or combination of key presses is surrounded by ++ with each key press separated with a single +.

Example

Output

Ctrl+Alt+Del.

Markdown

++ctrl+alt+delete++

The following key rendering is supported.

Emojies¶

Several sets of emojies are supported by entering the emoji name surrounded by colons: e.g :smile:. Below are list of common sets, those that are not rendered are currently not supported.

Mermaid¶

Mermaid.js diagrams are now supported natively.

Flowcharts¶

Flowcharts are diagrams that represent workflows or processes. The steps are rendered as nodes of various kinds and are connected by edges, describing the necessary order of steps:

graph LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];

    ``` mermaid
    graph LR
    A[Start] --> B{Error?};
    B -->|Yes| C[Hmm...];
    C --> D[Debug];
    D --> B;
    B ---->|No| E[Yay!];
    ```

Sequence diagrams¶

Sequence diagrams describe a specific scenario as sequential interactions between multiple objects or actors, including the messages that are exchanged between those actors:

%%{init: {'mirrorActors': false } }%%

sequenceDiagram

    autonumber
    participant G as package URL<br><br>(github/S3)
    participant M as metatran
    participant T as transifex
    participant F as filesystem<br><br>(path)
    G->>M: package file 
    T->>M: pull latest translation strings
    opt 
        note over M: swap base language
    end

    opt 
        note over M: include/exclude languages
    end
    M->>+F: New package file

    ``` mermaid
    %%{init: {'mirrorActors': false } }%%

    sequenceDiagram

        autonumber
        participant G as package URL<br><br>(github/S3)
        participant M as metatran
        participant T as transifex
        participant F as filesystem<br><br>(path)
        G->>M: package file 
        T->>M: pull latest translation strings
        opt 
            note over M: swap base language
        end

        opt 
            note over M: include/exclude languages
        end
        M->>+F: New package file
    ```

git graphs¶

Git graphs provide a pictorial representation of git commits and git actions on various branches.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'gitGraph': {
'showBranches': true, 
'showCommitLabel':false, 
'mainBranchName': 'master'}} 
}%%

gitGraph
    commit
    commit
    branch "2.39"
    checkout "2.39"
    commit
    checkout master
    commit
    checkout "2.39"
    branch "patch/2.39.0"
    checkout "patch/2.39.0"
    commit
    checkout master
    commit
    checkout "2.39"
    commit
    checkout "patch/2.39.0"
    commit tag: "2.39.0"
    checkout master
    commit
    checkout "2.39"
    commit
    commit
    checkout "master"
    commit
    checkout "2.39"
    branch "patch/2.39.1"
    checkout "patch/2.39.1"
    commit
    commit tag: "2.39.1"
    checkout "2.39"
    commit
    checkout "patch/2.39.1"
    branch "hotfix 2.39.1.1"
    commit tag: "2.39.1.1"

    ``` mermaid
    %%{init: { 'logLevel': 'debug', 'theme': 'dark', 'gitGraph': {
    'showBranches': true, 
    'showCommitLabel':false, 
    'mainBranchName': 'master'}} 
    }%%

    gitGraph
        commit
        commit
        branch "2.39"
        checkout "2.39"
        commit
        checkout master
        commit
        checkout "2.39"
        branch "patch/2.39.0"
        checkout "patch/2.39.0"
        commit
        checkout master
        commit
        checkout "2.39"
        commit
        checkout "patch/2.39.0"
        commit tag: "2.39.0"
        checkout master
        commit
        checkout "2.39"
        commit
        commit
        checkout "master"
        commit
        checkout "2.39"
        branch "patch/2.39.1"
        checkout "patch/2.39.1"
        commit
        commit tag: "2.39.1"
        checkout "2.39"
        commit
        checkout "patch/2.39.1"
        branch "hotfix 2.39.1.1"
        commit tag: "2.39.1.1"
    ```