README.tpl.md

meta	server
title Readme	index true

atwhy

What is atwhy

atwhy can be used to generate a documentation out of comments in the code.
That way you can for example describe all available options in the same file
where they are coded. A developer therefore doesn't have to know exactly where
the information has to be documented because it is just in the same file.

--> Single source of truth also for documentation!

Markdown templates are used to just group the tags together into files and add some non-code specific docu.

The idea of athwy was born during a company-hackathon and since then evolved to a first fully usable preview version.

Although most things are in a stable state, there may be small breaking changes until atwhy reaches v1.0.0.

Example

As atwhy itself uses atwhy very extensively, you can just

• look at the [templates]({{ .Project "templates" }}) folder of this project.
• and search for @WHY in the whole project.

Installation

You have several options to install atwhy:

• Just use docker to run a minimal image (It is multi-arch so it works on x64 and arm):
  docker run --rm -i -p 4444:4444 -u $UID:$GID -v $PWD:/project ghcr.io/tiffinger-thiel-gmbh/atwhy atwhy
  You may add an alias to your shell for this.
• Install Go and run go install github.com/Tiffinger-Thiel-GmbH/atwhy@latest.
  You may need to restart after installing Go to have the PATH setup correctly.
• Download a matching binary from the releases and put somewhere in your PATH.
  Note that they are currently not signed -> MacOS and Windows may not like that...

Usage

Command

{{ .Group "readme_usage" }}

Templates

The templates are by default inside the [templates]({{ .Project "templates" }}) folder of your project.
Each template results in one .md file. So if you have the file templates/README.tpl.md it will be generated to README.md. If you have the file templates/doc/Usage.tpl.md it will be generated to doc/Usage.md.

{{ .Group "doc_template_usage" }}

Header

{{ .Tag.doc_template_header }}

Tags

Tags are the heart of atwhy.
Basically you can add them in any comment of any file and then reference them in any of the templates.

{{ .Group "readme_tags" }}

The tags are terminated by

• another tag
• empty line
• Exception: @WHY CODE is terminated by @WHY CODE_END and not by empty lines.

Comments

You can specify the type of comments for each type of file. For this you may use the --comment flag.

{{ .Tag.readme_comments }}

The following are the default, built-in rules: {{ .Tag.readme_comments_builtin }}

Ignore

• You can pass something like --ext ".go,.js,.ts" to only process specific files.
• {{ .Tag.readme_ignore }}

Distribute

Prerequisites

• >= Go 1.18

Build

Run go build .

---

This README was last updated on: {{ .Now }}