Online documentation¶
It is recommended that DHI uses the common documentation framework Material for MkDocs for online help.
Contact: Kristian Thage
Audience¶
This document is intended for people maintaining product and project documentation as well as Product Owners and developers configuring documentation sites.
URL¶
The URL of online documentation should be based on using the URL format <Doc type>.<product name>.mikepoweredbydhi.com.
The documentation types are:
- userdoc
The product user guide. - api
The developer API documentation.
The Documentation Framework (Material for MkDocs)¶
It is recommended that DHI products use Python library Material for MkDocs for making online documentation.
Material for MkDocs is a documentation framework on top of the documentation framework MkDocs, providing a range of additional documentation features.
Documentation files are written in Documentation source files are written in Markdown, and configured with a single YAML configuration file.
Getting started¶
A documentation sites starts in an empty and dedicated documentation DevOps repository for the project or product.
The repository should contain the following structure of files.
- docs
- index.md
- .deployment
- .gitignore
- deploy.cmd
- Dockerfile
- mkdocs.yml
- push.cmd
- requirements.txt
- web.2.7.config
Copy an existing DHI documentation site as template and update only markdown files in the docs folder as well as the mkdocs.yml file.
Below, the files that should be changed are described.
docs¶
Folder containing the core index.md markdown file as well as all markdown files of the documentation.
mkdocs.yml¶
The Table of Contents file, where the structure and markdown files is maintained.
The below sample yml is taken from DHI Developers.
site_name: DHI Developers (Internal)
nav:
- 'index.md'
- 'NuGet access': 'nuget.md'
- MIKE Core SDK:
- 'About': 'core_libraries/core-libraries.md'
- 'Changelog': 'core_libraries/core-changelog.md'
theme:
name: 'material'
features:
- content.code.copy
markdown_extensions:
- admonition
- toc:
permalink: true
- pymdownx.arithmatex
- pymdownx.highlight:
use_pygments: true
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
- attr_list
extra_javascript:
- 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML'
extra:
search:
language: 'en'
tokenizer: '[\s\-\.]+'
requirements.txt¶
Text file containing the Python libraries and versions used. The Python libraries in this file will be installed on the documentation site.
For information about Python libraries, please visit the Python Package Index.
The sample below shows a sample file.
mkdocs>=1.5.2
Pygments>=2.16.1
mkdocs-material>=9.2.8
pymdown-extensions>=10.2.1
Maintain Content Pages¶
Markdown documentation files are maintained (added and removed) in the file mkdocs.yml.
Images¶
To ensure fast loading times and a good user experience without sacrificing too much quality, images file sizes should follow recommended guidelines.
- Icons/thumbnails as PNG or SVG < 1–50 KB
- Small images as PNG (e.g. snippets and small dialogs < 300 pixels) < 100 KB
- Medium content images (e.g. complete windows and large dialogs < 800 pixels) 100–300 KB
Do not use images larger than 800x600 pixels for online help.
When capturing images using image snipping tools, do not capture the image while the dialogs or windows are maximized. Always resize the windows and dialogs on screen before capturing an image.
It is recommended to limit the number of images used in the user documentation to show only nessesary images, as images takes up bandwidth and loading times increase.
Material for MkDocs¶
Material for MkDocs is recommended as the documentation framework.
Refer to the Material for MkDocs reference on how to write your documentation.
Markdown extensions¶
If needed, markdown extensions can be added to the file mkdocs.yml in the markdown_extensions: section.
Pipelines and publishing¶
Once the markdown documentation structure has been made, contact the DHI Infrastructure & Operations team for creating the build pipeline.
Jaroslav Kopriva is currently creating and maintaining the pipelines.
Once the build pipeline has been created, the online documentation will be automatically published using the pipeline when check-ins are done to the main branch.
Note
It is required to use branching policies for documentation repositories so that reviews (and pull-requests) are required for geeting documentation updated in the master/main branch.
Working in branches, will prevent unnessesary load on the network and to avoid costs and increase requests to the documentation site as user local cache is out of date.
DHI Documentation Sites¶
Various existing DHI documentation sites has been created using MkDocs.
DHI Developers¶
This site is meant for internal DHI users only and contains both external and internal information. It contains information about all the different APIs and developer resources which have been used in various parts of DHI. There is an external site with only external information which will be deployed seperately and is located here. (not implemented yet).
DHI Developers includes developer documentation for:
- MIKE Core
- MIKE Engine SDK
- MIKE OPERATIONS
- MIKE+
- Domain Services
- MPC
Find contact information in the DHI Developers documentation URL
MIKE OPERATIONS¶
The MIKE OPERATIONS Online documentation has been made with Material for MkDocs.