github-docs

github-docs is CLI application that automatically generates documentation for your GitHub actions & workflows. It was inspired by terraform-docs.

This was an Everpure Hackathon project by Andrei Gatea, Miroslav Brabenec & Radek Sprta.

Features

• render documentation in Markdown
• print output to stdout or save into file
• inject generated documentation into README.md, or completely replace it
• run as pre-commit hook
• take one or more files or directories as input (directories are searched recursively)
• shell completion

Requirements

github-docs requires Python 3.11 or newer to run.

Installation

You can build and install the package manually. The repository requires SSH certificate authentication, so the clone URL carries the organisation's SSH alias and HTTPS will not work:

git clone [email protected]:PureStorage-OpenConnect/github-docs.git
cd github-docs
uv build
pip install --user dist/*.whl

Usage

For help, run github-docs --help. Here are some common patterns:

Print action docs to stdout

github-docs action action.yml

Inject actions docs to file

github-docs action action.yml --output-file README.md

Docs will be injected between <!-- BEGIN_GITHUB_DOCS_BLOCK --> & <!-- END_GITHUB_DOCS_BLOCK --> markers in your file. If the file has neither marker, the block is appended to its end.

Replace file with workflow docs

github-docs workflow .github/workflows --output-file README.md --mode replace

Document several definitions at once

github-docs action .github/actions --output-file README.md

You can pass any number of files and directories. --output-file is a filename, not a path — it is written beside each definition, in the directory its source file lives in. Definitions that share a directory share one document, so the command above writes one README.md per action directory under .github/actions, while pointing workflow at .github/workflows (where every reusable workflow lives flat in one directory) writes a single shared README.md there. With no --output-file, everything still concatenates to stdout, following the order the paths were given, with definitions inside a directory sorted by path.

Directories are searched recursively, because the conventional layout puts each action in its own subdirectory (.github/actions/<name>/action.yml); a non-recursive search of .github/actions would find nothing. Overlapping arguments are de-duplicated, so passing both a directory and a file inside it documents that definition once.

Pre-commit hook

To use the with the pre-commit framework, add the following to your pre-commit-config.yaml:

The hook rewrites the output file beside each changed definition; pre-commit fails the commit when any file was modified by the hook. Re-stage the rewritten files and commit again. Your args choose the subcommand and the output filename.

Actions

---
repos:
  - repo: [email protected]:PureStorage-OpenConnect/github-docs.git
    rev: pre-commit
    hooks:
      - id: github-docs
        args: [action, --output-file, README.md]

Workflows

---
repos:
  - repo: [email protected]:PureStorage-OpenConnect/github-docs.git
    rev: pre-commit
    hooks:
      - id: github-docs-workflow

The workflow hook documents every reusable workflow in .github/workflows whenever any of them changes, writing README.md there by default. Your args replace the default ones, so keep --output-file in them, e.g. args: [--output-file, README.md, --mode, replace]; without it the docs only go to stdout and no file is updated.

Contact

[email protected]