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.

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

--[[
% chromatic_transposition(note, interval, alteration, simplify)

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.

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

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

If you find a bug, create an issue.

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