Průvodce dokumentací DHIS 2¶

DHIS 2 Dokumentace Přehled Systému¶

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.

Úvod¶

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.

Začínáme s 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

Nejlepší způsob, jak najít zdroj dokumentu, který chcete upravit, je najít dokument na webu docs.dhis2.org a kliknout na ikonu „Upravit“ v horní části stránky.

Získání zdroje dokumentu¶

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. Ujistěte se, že máte nainstalovaný git.

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.

Úpravy dokumentace¶

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.

Používání obrázků¶

Zdroje obrázků by měly být zahrnuty jako relativní cesty uvnitř podsložky vzhledem k aktuálnímu dokumentu. např. pro kapitolu content/android/android-event-capture-app.md jsou obrázky někde pod content/android/resources/images/<rest-of-path> a jsou odkazovány jako ![](resources/images/<rest-of-path>)

Styling images¶

Pokud chcete ovládat zarovnání a velikost obrázků, můžete využít rozšíření markdown, které používáme. Umožňuje nastavit atributy, jako je šířka, výška a třída ve složených závorkách na konci definice obrázku. Například:

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

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

Když jsou obrázky psány jako

![Schvalování a přijímání](resources/images/data_approval/approval_level_steps.png)

Taking screenshots¶

Pro snímky obrazovky webového rozhraní DHIS 2 doporučujeme použít prohlížeč Chrome s následujícími dvěma rozšířeními: 1. Window Resizer. Použijte toto k nastavení rozlišení na 1440x900 2. Fireshot. Použijte toto k rychlému vytvoření snímku viditelné části

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)

Při pořizování snímků obrazovky aplikace pro Android by měla být velikost nastavena na 360x640.

Localising images¶

Lokalizace obrázků je podporována ukládáním jazykových verzí obrázku vedle původního obrázku. Název souboru by měl být stejný jako původní anglická verze, ale měl by obsahovat _ plus kód jazyka na konci názvu před příponou.

Například, pokud chcete mít francouzskou verzi resources/images/my_screenshot.png Můžete jednoduše vytvořit francouzskou verzi a uložit ji jako resources/images/my_screenshot_fr.png

Odkaz v dokumentaci by měl stále ukazovat na původní obrázek. Když je stránka dokumentace vytvořena pro každý jazyk, lokalizované obrázky budou identifikovány a použity místo anglických originálů.

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.

Odkazy na sekce¶

Abychom v dokumentaci poskytli pevné odkazy (kotvy), můžeme nastavit pevný textový řetězec, který se použije na jakoukoli sekci. U našeho markdown procesoru se to provádí přidáním hash id do složených závorek na konec řádku s názvem sekce, např.

## Ověření { #webapi_validation }

Chcete-li vygenerovat shrnutí ověření dat, můžete pracovat ...

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.

Dodržujte prosím konvenci malých písmen a podtržítek, abyste vytvořili ID platná také jako názvy souborů v případech, kdy rozdělujeme soubory jako součást generování dokumentu.

Tabulky¶

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|

který produkuje výstup jako:

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 Bibliografie¶

Bilbliografické odkazy aktuálně nejsou podporovány v markdown verzi dokumentace DHIS 2.

Zpracování vícejazyčné dokumentace¶

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.

Potvrzení změn zpět na 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.

Podpora a rozšíření Markdown¶

Tato část se pokusí zachytit označení a rozšíření, které jsou podporovány pro dokumentaci DHIS 2, a poskytnout náhled použitých stylů.

h3 Nadpis¶

h4 Nadpis¶

h5 Nadpis¶

h6 Nadpis¶

Základní text.

Horizontální linky¶

___

---

***

Zvýraznění¶

Toto je tučný text

This is bold text

This is italic text

Toto je kurzíva

Přeškrtnutí

Blokové uvozovky¶

> 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 }

Kód¶

Vložený code

Vložený zvýrazněný kód var test = 0; vytvořený uvnitř

`#!js var test = 0;`

Odsazený kód

// Nějaký komentář
line 1 of code
line 2 of code
line 3 of code

Blokový kód "fences"

Ukázkový text zde ...

Zvýraznění syntaxe

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

console.log(foo(5));

Dlouhé línie

Buffalo buffalo (zvířata zvaná "buffalo" z města Buffalo) [ten] Buffalo buffalo buffalo (že zvířata z města Buffalo) buffalo Buffalo buffalo (šikanuje tato zvířata z tohoto města).

Zvýrazněte konkrétní řádky

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]
```

Seznamy¶

Neuspořádané

• Vytvořte seznam novým řádkem s +, -, or *
• Dílčí seznamy se vytvářejí odsazením 2 mezer:

  • Změna znaku značky vynutí nový začátek seznamu:

    • Ac tristique libero volutpat at

    • Facilisis v pretium nisl aliquet

      an indented code block
      

    • Nulla volutpat aliquam velit

    • Velmi snadné!

Seřazeno

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

3. Integer molestie lorem at massa

4. Můžete použít sekvenční čísla...

5. ...nebo ponechte všechna čísla jako 1.

Začnete číslovat s odsazením?:

1. foo
2. bar

Víceúrovňové

1. první položka
2. stále první úroveň
   1. druhá úroveň
   2. stále druhá
      1. třetí úroveň

         a block of code at the third level
         

      2. stále třetí úroveň
   3. druhá úroveň znovu
3. zpět na první úroveň
   1. druhá
      1. Přestaň s tím!

Tabulky¶

Sloupce zarovnané doprava a na střed

Odkazy¶

link text

link with title

Automaticky převedený odkaz https://github.com/dhis2

Obrázky¶

Obrázky se zobrazují v plné velikosti s maximální šířkou 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)

Připomenutí¶

Kromě obecných uvozovek jsou podporovány následující uvozovky s předdefinovanými styly.

Poznámka¶

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

Důležité¶

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

Pozor¶

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

Varování¶

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

Probíhající práce¶

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

Příklad¶

> **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));
> ```

Matematické rovnice¶

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

Typografické náhrady¶

Dolní index / horní index¶

- 19^th^
- H~2~O

• 19^th
• H₂O

++Vložený text++

Označený text

Poznámky pod čarou¶

Odkaz pod čarou 1 link¹.

Odkaz pod čarou 2 ².

definice Vložená poznámka pod čarou ^[Text vložené poznámky pod čarou]

Duplikovaný odkaz pod čarou [^druhý].

Seznamy definic¶

Term 1

Definition 1 with lazy continuation.

Term 2 with inline markup

Definition 2

{nějaký kód, součást definice 2}

Třetí odstavec definice 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:

graf LR
A[Start] --> B{Chyba?};
B -->|Ano| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|Ne| 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 poskytují obrazovou reprezentaci git commitů a git akcí v různých větvích.

%%{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"
    ```