dhis2-docs: Documentation for DHIS 2 in markdown format

代码拉取完成,页面将自动刷新

扫描微信二维码支付

取消

支付完成

richgiteeai

Watch

不关注关注所有动态仅关注版本发行动态关注但不提醒动态

1 Star 0 Fork 0

easylin/dhis2-docs

代码 Issues 0 Pull Requests 0 Wiki 统计流水线

服务

加入 Gitee

与超过 1400万开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)

免费加入

已有帐号? 立即登录

该仓库未声明开源许可证文件(LICENSE),使用请关注具体项目描述及其代码上游依赖。

项目仓库所选许可证以仓库主分支所使用许可证为准

克隆/下载

HTTPS SSH SVN SVN+SSH 下载ZIP

提示

下载代码请复制以下命令到终端执行

为确保你提交的代码身份被 Gitee 正确识别,请执行以下命令完成配置

git config --global user.name userName 
git config --global user.email userEmail

初次使用 SSH 协议进行代码克隆、推送等操作时,需按下述提示完成 SSH 配置

1 生成 RSA 密钥

2 获取 RSA 公钥内容,并配置到 SSH公钥中

在 Gitee 上使用 SVN,请访问使用指南

使用 HTTPS 协议时,命令行会出现如下账号密码验证步骤。基于安全考虑,Gitee 建议配置并使用私人令牌替代登录密码进行克隆、推送等操作

Username for 'https://gitee.com': userName

Password for 'https://userName@gitee.com': # 私人令牌

新建文件新建 Diagram 文件

新建子模块

上传文件

分支 268

标签 1

贡献代码

同步代码

创建 Pull Request

了解更多

对比差异通过 Pull Request 同步

同步更新到分支

通过 Pull Request 同步

将会在向当前分支创建一个 Pull
Request,合入后将完成同步

Jim Grace docs: Predictor minDate and maxDate DHIS2-... 6ab141d

1586 次提交

src

.gitignore

README.md

fdl-1.3.txt

README

# DHIS 2 Documentation

All of your favourite documentation - in markdown format!

# Updating the documents
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.

## Format and editing
The documents are maintained in [commonmark](https://commonmark.org/help/) 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, [Typora](https://typora.io/) is a great, open-source markdown editor.

### Structure

The structure of the documentation site is defined in the build repository [dhis2-docs-builder](https://github.com/dhis2/dhis2-docs-builder).

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

### Adding 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% }
```
will make your image 50% of the page width (it is best to use percentages to support a variety of output forms), while
```
![](resources/images/maintainence/predictor_sequential.png){ .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
```
![Approving and accepting](resources/images/data_approval/approval_level_steps.png)
```
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.

#### Taking screenshots

For screenshots of the DHIS 2 web interface, we recommend using Chrome browser, with the following two extensions:
1. [Window Resizer](https://chrome.google.com/webstore/detail/window-resizer/kkelicaakdanhinjdeammmilcgefonfh?hl=en). Use this to set the resolution to **1440x900**
2. [Fireshot](https://chrome.google.com/webstore/detail/take-webpage-screenshots/mcbpblocgmgfnpjjppndjkmgjaogfceg?hl=en). 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:

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

> **Important**
>
> **Please try to use GFM tables** as they give much better support for translations. 
> 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).

> **Tip**
>
> If you want to apply a caption to your markdown tables, add a preceding block starting with "Table: " followed by the caption title. 
> e.g. the following results in the caption "Data store structure" 
>
>```
> Table: Data store structure
>
>| Item | Description | Data type |
>|---|---|---|
>| Namespace | Namespace for organization of entries. | String |
>| Key | Key for identification of values. | String |
>| Value | Value holding the information for the entry. | JSON |
>| Encrypted | Indicates whether the value of the given key should be encrypted | Boolean | 
>```
>(Note: in GitHub you will just see the "Table: ..." block as text, but it will be rendered as a caption in the docs site)

### INCLUDES

`!INCLUDE` directives can be used to include the contents of another markdown file into the current one.

```
!INCLUDE "../other_directory/other_file.md"
```

Use relative links for `!INCLUDE` directives.

> **NOTE**
>
> the `!INCLUDE` directives are not part of pure commonmark format, but are used in pre-processing to build the master documents.

### "DHIS2" or "DHIS 2", that is the question

Historically, 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. **Note that we are now moving towards applying the compact form "DHIS2" consistently across documentation**.

# Building the documents

See the build repository [dhis2-docs-builder](https://github.com/dhis2/dhis2-docs-builder) for information about biulding the documents