Skip to content

Dev Guide - Creating Diagrams

Oops... TODO / WIP page

This page is not completed!

There are a few options to provide diagrams to this documentation:

  • Migrammer
  • Mermaid
  • Images (static)
  • Draw.io / Diagrams.net

Attention

We will not store images directly to the source code.

The steps below will share how you can embed diagrams to the guides/documentation without needing to add images to the CVS.

Migrammer

The migrammer allows you to create Diagram as a Code. The mkdocs on this project will auto-build python diagrams to allow you to reference the images to the documentation.

To create an standard of diagrams, all the python files must be under the directory docs/diagrams/, and all the images generated by the diagrams should be under docs/diagrams/images - ignored by github.

An example diagram is provided on docs/diagrams/example.diagram.py and the image will be generated on docs/diagrams/images/example.png.

  • Code:
  • Referencing the image

Example Diagram

Mermaid

You also can add Mermaid charts directly on the markdowns.

A short example of the flow:

%%{init: {"flowchart": {"useMaxWidth": false}}}%%

sequenceDiagram
  autonumber
  User->>okd-installer-plays: install_clients
  okd-installer-plays->>okd-installer-roles: role=clients
  loop Download clients
      okd-installer-roles->>okd-installer-roles: openshift-installer
      okd-installer-roles->>okd-installer-roles: oc
      okd-installer-roles->>okd-installer-roles: butane
  end
  okd-installer-roles->>okd-installer-plays: OK
  okd-installer-plays->>User: OK
  User->>okd-installer-plays: create_all
  loop Run playbooks
      okd-installer-plays->>okd-installer-roles: create Config/Stack
      okd-installer-roles->>okd-installer-plays: finish
  end
  okd-installer-plays->>okd-installer-roles: approve worker certs
  okd-installer-roles->>okd-installer-plays: done
  okd-installer-plays->>User: done
  User->>Cluster: oc get nodes

Images (static)

Static images can be added to the documentatoin by uploading it to the Wiki Page with the prefix image/, then the URL can be referenced on the docs.

Draw.io / Diagrams.net

You can embed the Diagram from Diagrams.net directly to the markdown file by following the option: File > Embed > Html...