Contributing to the DINO Documentation¶

Thank you for helping improve the DINO documentation!
This guide explains how to contribute using MkDocs and Markdown (.md) files.

1. Documentation Structure¶

The documentation is structured in different sections that are structured intuitively:

Home: Landing Page
Getting Started:
- Requirements: Description of required libraries
- Installation: A detailed description to install the code on any HPC system.
User Guide:
- Code Structure: Explanation of the root directory and the different subfolders and files of DINO
  - Modules: Information on the different MODULES that are contained in DINO
  - Workflow Overview: A brief overview of the workflow of DINO
- Parallelization Strategy: Short introduction to the domain decomposition and parallelization
- Input Files: An overview on the different input files necessary for simulations
  - Main Input File: Detailed description of the DINO_IN input file written in fortran namelist
    - Initialize: Description and details for all input flags of the INITIALIZE block of the DINO_IN File
    - etc.
Tutorials:
- Beginner: A beginner level tutorial, using a 0D homogeneous reactor simulation to calculate auto ignition of a hydrogen air mixture
- Intermediate: A 1D premixed flame case, taylored as a tutorial for intermediate users.
- Advanced: An advanced tutorial to incorporate more advanced simulation techniques and longer simulation times.
Contributing:
- Code development: Information on how developers can contribute to DINO
- Contribute to the docs: Explanations on how to contribute to the DINO documentation
About: Information on the development team as well as the license, under which DINO is distributed

All pages are written in Markdown and built with MkDocs and the installation and usage are described in the following.

2. Workflow to Contribute¶

2.1 Setting up a Virtual Environment for Documentation¶

To contribute to this documentation, it is recommended to create a python virtual environment for the documentation only:

    python -m venv doc_venv

This command will create a virtual environment called doc_venv and create a folder contianing all executables. You can activate it by typing:

    source doc_venv/bin/activate

You can now install mkdocs using the simple command:

    pip install mkdocs

And check the installed libraries:

    pip list

The DINO documentation uses the material theme for mkdocs, that must be installed:

    pip install mkdocs-material

Now you will need to install a few plugins for mkdocs:

    pip install mkdocs-bibtex
    pip install mkdocs-git-glightbox
    pip install mkdocs-git-revision-date-localized-plugin
    pip install mkdocs-to-pdf
    pip install mike

You are now ready to contribute to the DINO documentation.

2.2 Git Usage¶

Any new contribution should be prepared in a seperate git branch, to enable parallel development and continuous version control. Branches should be named by the new feature that is implemented:

git clone git@code.ovgu.de:dino/dino-documentation.git
cd dino-documentation
git checkout -b my-new-feature

Every commit should have a short and easy to understand message:

    git commit -m 'My easy message, containing important information'

Informations can then be pushed to the online repository:

    git push

Once your developments are finished, you can create a merge request, either on the GitLab page itself or by the terminal:

    git checkout master
    git merge my-new-feature

which will create a merge request of the specified branch's history into the master branch (or current one).

3. Editting/Adding Documentation Pages¶

All pages are written in Markdown .md files in the docs/ subdirectory. A detailed description of all possibilities are given on the material github pages, but the general structure can be found in already existing documentation pages.

You can see your changes live by hosting a server locally:

    mkdocs serve --livereload

This command will launch a server, that you can call in your local browser under the given address.

The documented features should be placed according to the used structure and be registered in the mkdocs.yml under the appropriate section. The mkdocs.yml file is located in the root directory.

3.1 Style Rules¶

To keep the documentation clear and intuitive, different rules regarding style and language should be followed:

write in clear, concise technical English
prefer imperative tone (e.g. "Run the command ...")
Use active voice where possible
when adding theory, include equations as fenced $$ blocks (MathJax enabled)

Any documentation must be USER oriented and written in manner that makes the documentation understandable, even for unexperienced users. Keep in mind: The documentation is not written for yourself, the developer who implemented something new to the code, but users who might have never worked with DINO before.

For consistency, mimic existing pages when in doubt.

3.2 Validation before submitting¶

Before submitting your changes and merge your branch to the master branch, run:

    mkdocs build --strict

Your private branch should build without any errors or warnings. Additionally check that: - internal links resolve - no placeholder text remains - navigation entries are correct

3.3 Questions or discussing changes¶

Any merge request should contain a description that includes:

What was added/changed
Which section(s) of the docs were affected

Every merge request undergoes a review for:

technical correctness
clarity and tone
consistency with tstyle
build/reproducibility validity

No merge will happen without an approval.

4. License¶

By contributing, you agree that your contributions are submitted under the same license as the repository.