47 lines
1.3 KiB
Markdown
47 lines
1.3 KiB
Markdown
# Documentation Guidelines
|
|
|
|
Best practices and guidelines for writing code documentation.
|
|
|
|
## Release Notes
|
|
|
|
The idea is to get rather automated release notes. To have this as easy as possible, we need:
|
|
|
|
- key words for the kind of change we applied:
|
|
- `feature:` - for newly added functionality
|
|
- `fix:` - for bugfixes
|
|
- `nonotes:` - for git commits we don't want to see in the release notes
|
|
|
|
- tags for each version, we will output only the change log from the last and second last tag
|
|
- you can add tags with `git tag -a <tag> -m "<message>"`
|
|
|
|
[resources/scripts/release-notes.bash](resources/scripts/release-notes.bash) is an example bash script to generate the release notes. You can run it with the following command:
|
|
|
|
```bash
|
|
bash resources/scripts/release-notes.bash
|
|
```
|
|
|
|
## 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
|
|
```
|