59 lines
1.4 KiB
Markdown
59 lines
1.4 KiB
Markdown
# 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
|
|
```
|