# Documentation Guidelines

Best practices and guidelines for writing code documentation.

## Formats

All documentation should be easy maintain and accessible. Easy formats should be preffered over more complex ones.

## PlantUML

Create png images from PlantUML files using the following command:

```bash
plantuml -tpng <file>.puml
```

## Draw.io Diagrams

Ensure to have the draw.io application aliased. This example is for a macOS based system configured with ansible:

```yaml
- name: Add Draw.io alias to .zshrc
  lineinfile:
    path: "/Users/{{ macos_user }}/.zshrc"
    line: "alias drawio='/Applications/draw.io.app/Contents/MacOS/draw.io'"
    state: present
```

Create png images from Draw.io diagrams using the following command.

```bash
drawio -x -f png -b 10 -o <output>.png <file>.drawio
```

## Folder Structure

If you want to add an optional folder structure to your documentation, you can use the following command to generate a tree-like structure.

```bash
git ls-tree -r --name-only HEAD | sed 's|[^/]*|   &|g'
```

Example output:

```text
   Dockerfile
   maus_helper.sh
   maus_loader.yml
   requirements.txt
   setup.py
   src/   __init__.py
   src/   logging_config/   __init__.py
   src/   logging_config/   config.py
   src/   maus_loader.py
   src/   scraper/   __init__.py
   src/   scraper/   scraper.py
   tests/   __init__.py
   tests/   test_scraper.py
```