Skip to content
book-open

GitHub Action

Generate lua docs

1.3.1 Latest version

Generate lua docs

book-open

Generate lua docs

Create documentation from lua scripts

Installation

Copy and paste the following snippet into your .yml file.

              

- name: Generate lua docs

uses: finale-lua/lua-docs-generator@1.3.1

Learn more about this action in finale-lua/lua-docs-generator

Choose a version

Lua docs generator

This is a JavaScript script that will create documentation from Lua source code. It parses any Lua files in the current directory for multi-line comment blocks and sequentially adds them to a Markdown file (Github flavored Markdown). It is inspired by p3lim/lua-doc-parser.

It supports many aspects of ExpLua to create very clean documentation. For more details, see documentation.md.

Usage

For documenting your lua scripts, just add multiline comments. All valid markdown is allowed in these multiline comments. For instance, this comment…

--[[
% chromatic_transposition

A description of how the code works

@ first (string) Text of the first parameter
@ [optional] (any) Optional parameters to be called whatever

: (number) Number of whatever is done or nil if an error occurred
--]]

…produces this markdown.

markdown-image.png

For more details, see documentation.md. For more examples on how this script parses Lua files, check out the test-files folder.

Action Inputs

Name Description
input (required) The folder of the lua scripts
output (required) The folder where to save the documentation

Example workflow

name: Generate docs

on: push

jobs:
  test-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: nick-mazuk/lua-docs-generator@v1
        with:
          input: '.'
          output: './docs'
      - name: Push updated docs
        run: |
          git config user.name CI
          git config user.email "<>"
          git add .
          git diff --quiet HEAD || git commit -m "$GITHUB_SHA"
          git push

Bugs

If you find a bug, create an issue.

Contribute

I welcome contributions! This repo follows the "fork-and-pull" philosophy. If you're going to add a feature, please create an issue first so we can keep track of it.

To get started, fork the repository and install the dependencies.

pnpm install

And before you submit your pull request, make sure to lint, format, and test everything. I will not accept PRs unless the code passes each of these.

pnpm lint # also fixes formatting
pnpm test