Automate documentation for workflows and actions

[yannick-roeder]

The documentation usually contains a lot of information that is already present inside the corresponding action or workflow (e.g. inputs). Ideally we can mainly automate the process of creating the documentation.

Acceptance Criteria

• Support documentation generation for both actions and reusable workflows

Following informations are in the documentation:

• table of Inputs and output vars
• table of secrets

• Allow documentations update of individual sections (e.g. by specifying blocks where to add the auto generated doc) -> follow up issue
• The generated doc should contain the same column as the current docs
• Allow listing of action dependencies -> not supported
• Use pre-commit locally and in a corresponding workflow to enforce developers to generate documentation for actions and workflows locally

• hook based on auto-doc CLI
• hook should always generate docs
• hook should fail when changes are made (exit 1)
• hook should succeed when no changes were made (exit 0)
• local bug needs fixing: Currently the python script needs to be changed every time for pre-commit to work properly, this is not desired
• GitHub CI workflow should also execute pre-commit without committing and pushing (output should contain failed hooks and list of files that need generation/formatting)

• Test script installation of auto-doc on Windows, Linux and MacOs

Timeline

Demo for automatic generation of docs for all workflows and actions on 29th of November:

• implementation of pre-commit hook didn't work as expected yet
• formulation of new acceptance criteria for pre-commit hook (see above)

Next Demo for automatic generation of docs for all workflows and actions on 4th of December

• local bug: Currently the python script needs to be changed every time for pre-commit to work properly, this is not desired
• workflow did not work as expected yet (didn't execute pre-commit and didn't list files that need to be changed)

Next Demo on 6th of December

[MichaelKora]

• https://github.com/npalm/action-docs
• https://github.com/tjtharrison/github-actions-docs
• https://github.com/bitflight-devops/github-action-readme-generator
• https://github.com/tj-actions/auto-doc

[yannick-roeder]

Closed by #161