py-lua-doc

A Lua documentation extraction tool written in Python that support emmy-lua and ldoc doc-comment.

It's both a development library and a command line tool.

Given a lua source file, it creates a documentation model.

Installation

The package can be installed through pip:

$ pip3 install luadoc

It will install the shell command 'luadoc'.

How to generate documentation ?

This project is part of a Sphinx documentation plugin: sphinx-lua

Node Structure

The node structure is for now only described in model.py

Command Line

The command line tool just serialize the tree to Json.

Given:

--- @classfoo.BaselocalBase= {}
--- @classfoo.List:foo.BaselocalList= {}
--- Apply a function to all elements.--- Any extra arguments will be passed to the function.--- @paramfunfun(a:any):any a function of at least one argument--- @varargany @arbitrary extra arguments.--- @returnfoo.List a new list: {f(x) for x in self}functionList:map(fun, ...) end--- Split a string using a delim.--- @paramdelimstring the delim (default "")--- @overloadfun()functionList:split(delim) endreturnList

$ luadoc source.lua

The following output will be produced:

{
"filename": "test.lua",
"classes": [
{
"name": "foo.Base",
"name_in_source": "Base",
"methods": [],
"desc": "",
"usage": "",
"inherits_from": [],
"fields": []
},
{
"name": "foo.List",
"name_in_source": "List",
"methods": [
{
"name": "map",
"short_desc": "Apply a function to all elements.",
"desc": "Any extra arguments will be passed to the function.",
"params": [
{
"name": "fun",
"desc": "a function of at least one argument",
"type": {
"id": "callable",
"arg_types": [
{
"id": "any"
}
],
"return_types": [
{
"id": "any"
}
]
},
"is_opt": false,
"default_value": ""
},
{
"name": "...",
"desc": "arbitrary extra arguments.",
"type": {
"id": "any"
},
"is_opt": false,
"default_value": ""
}
],
"returns": [
{
"desc": "a new list: {f(x) for x in self}",
"type": {
"id": "custom",
"name": "foo.List"
}
}
],
"usage": "",
"is_virtual": false,
"is_abstract": false,
"is_deprecated": false,
"is_static": false,
"visibility": "public"
},
{
"name": "split",
"short_desc": "Split a string using a delim.",
"desc": "",
"params": [
{
"name": "delim",
"desc": "the delim (default \"\")",
"type": {
"id": "string"
},
"is_opt": false,
"default_value": ""
}
],
"returns": [],
"usage": "",
"is_virtual": false,
"is_abstract": false,
"is_deprecated": false,
"is_static": false,
"visibility": "public"
},
{
"name": "split",
"short_desc": "Split a string using a delim.",
"desc": "",
"params": [],
"returns": [],
"usage": "",
"is_virtual": false,
"is_abstract": false,
"is_deprecated": false,
"is_static": false,
"visibility": "public"
}
],
"desc": "",
"usage": "",
"inherits_from": [
"foo.Base"
],
"fields": []
}
],
"functions": [],
"data": [],
"name": "unknown",
"is_class_mod": false,
"short_desc": "",
"desc": "",
"usage": ""
}

Many other examples can be seen in luadoc/tests/source.