Documentation Guidelines#

Section Author

D. Rieger

We want to encourage all ICON developers in contributing to the ICON documentation (docs.icon-model.org). Your contributions to improve the coverage and readability of this website are necessary and always welcome!

The ICON documentation is written in an extended form of Markdown, which should be a familiar format for users of Gitlab, Github and thus ease the creation of documentation. Further information on the software used to generate the HTML website from Markdown is available on the websites listed in the useful links section.

The following section provide you with some information on the publication workflow, a starting point, the terms of reference and several examples.

Publication Workflow#

The documentation is located in the subfolder doc/www. Changes in this subfolder will trigger the CI/CD pipeline and generate a HTML preview. A View app button will appear in the merge request overview website (right below the pipelines) which will lead you to the HTML preview.

When a new ICON release is published, the docs.icon-model.org Website is deployed correspondingly. A preview of the content from the current icon:main is deployed under https://icon.gitlab-pages.dkrz.de/icon. Both are publicly accessible.

How to Start#

Since the documentation is part of the ICON repository, documentation updates take place in merge requests, following the same workflow as code developments. Ideally, code developments should always be accompanied by documentation updates. Merge request can be used to experiment with modifications in the doc/www subfolder. There exist already many solutions and examples for specific formats, admonition, tables or figures, some are outlined in detail below. Probably you will find an example/solution for your problem somewhere in the code or in the documentation of the software used to generate the website.

Best Practices

Please settle all data protection issues in advance.
Please keep the number of warnings at zero. The pipeline will fail otherwise.
As there is no automatic mail obfuscation in Sphinx, you might want to obscure mail adresses manually to avoid Spam
Please locate static content like images and pdfs used in the documentation in the same directory as the file where it is referenced to ease (relative) referencing, moving and tidying up content.
New subsites should not be added to the toctree in index.md since this information is used to generate the links in the header of the website.

Examples#

Tables#

A table with a caption can be created like this:

Table 1: Example table#
Column 1	Column 2
Text	More Text

Figures#

Here is an example to include a figure, or better two figures, one for dark mode (:class: only-dark) and one for light mode (:class: only-light).

Figure 1: Example figure

Namelist References#

Since the Namelist Overview is part of docs.icon-model.org, namelist parameters can be referenced from anywhere of docs.icon-model.org, e.g.

iforcing

Admonitions#

To highlight a short piece of information, the admonition-icontheme can be used

Some Highlight

Description of the highlight.

Highlighting with material icons#

In-line highlighting, e.g. for warnings, can be achieved using material icons. See also the sphinx-design documentation for further information.

Some setting

Some information

Some warning

Equations#

Equations are rendered via JavaScript using mathjax for sphinx. This allows for the usage of LaTeX syntax to generate equations:

(1)#\[\alpha^2 = \frac{\beta}{\Gamma}\]

Inline math is possible, e.g. \(\alpha=42\).

If a label is provided, an equation can be referenced at later point, e.g. equation (1).

Listing#

Apart from the usual hyphon or astrisk syntax in markdown, it is possible to create definition lists which include descriptions of the list items in the following way:

List Item: Description of the list item.

Intellectual Property Rights#

Authors may optionally put their name to a section they provided to the documentation. This has no affect on the license. This may serve several purposes:

Marking the intellectual property rights, thus easing a citation of the respective section
Provide a contact point for users in case of questions
A section may not be changed without the consent of the section author

if an author decides to mark the intellectual property right of a section, a macro must be used directly below the section heading for a unified appearance of the web site:

Section Author

A. Name

Or optionally with institution XYZ:

Section Author

A. Name, XYZ

Terms of Reference#

The task of the docs subsite is to collect:

Model documentation (not to replace scientific documentation!)
Material to run particular configurations
Introductory material (e.g. Tutorials, Training, …)

We do not want:

Project websites for particular developments
Replace or repeat scientific documentation which is published and available.

Useful Links#

Sphinx: Read RST or Markdown to generate HTML website
PyData Sphinx Theme: A clean, Bootstrap-based Sphinx theme
MyST: Markedly Structured Text - Parser
sphinx{design}: Extension to design screen-reponsive web components