sphinx-lua

A lua-autodoc tool for Sphinx. Generate a beautiful sphinx doc using lua doc comment.

It use emmylua as primary doc syntax but it is also compatible with some ldoc tags.

Installation

$ pip install sphinx-lua

Dependencies:

• Jinja2 (to render rst template)
• luadoc (to parse lua comments)
• sphinxcontrib-luadomain (to add lua domain to sphinx)

Sphinx integration

Add the following to your conf.py:

extensions= [
'sphinxcontrib.luadomain',
'sphinx_lua'
]
# Available options and default valueslua_source_path= ["./"]
lua_source_encoding='utf8'lua_source_comment_prefix='---'lua_source_use_emmy_lua_syntax=Truelua_source_private_prefix='_'

The lua_source_path configuration value tells to sphinx-lua where to find lua source code.

With above configuration, if main.lua is located in ../src/lua/main.lua, and it's content is:

--- Define a car.--- @classMyOrg.Carlocalcls=class()
--- @paramfoonumberfunctioncls:test(foo)
end

You can autodoc it in sphinx with the following directive:

.. lua:autoclass:: MyOrg.Car

Troubleshooting

Sphinx-lua use the documentation model extracted from luadoc (https://github.com/boolangery/py-lua-doc)

So you can print this model out using the command line tool:

$ luadoc ../src/lua/my_problematic_source_file.lua

Available sphinx directives

The following directives are available:

.. lua:autoclass:: pl.List.. lua:automodule:: pl.stringx.. lua:autoclasssummary:: ^pl... lua:autoalias:: SourceFn

automodule also accepts a regex, documenting every matching module in one call, which is handy to generate the whole documentation for everything found in lua_source_path:

.. lua:automodule:: .*

@alias tags are rendered as lua:alias directives (either standalone via autoalias, or automatically as part of automodule's output), and any @param/@return/@field referencing an alias or class by name is turned into a link to its definition:

---@aliasSourceFnfun():string|nil,string|nil---@paramcallbackSourceFnlocalfunctionsome_function(callback)
end

A method whose name is a known Lua metamethod (__index, __eq, __call, etc., per the Lua 5.4 manual) is automatically rendered with lua:metamethod instead of lua:method:

---Compare two instances for equality.---@paramselfClass---@paramotherClass---@returnbooleanfunctioncls.__eq(self, other)
end

Markdown-style fenced code blocks (as commonly used in EmmyLua doc comments) in descriptions are rendered as proper, syntax-highlighted code blocks:

---Returns 16-bit color.------Example:---```lua---local color = display.color565(255, 0, 0)---```functiondisplay.color565(r, g, b) end

You can also use directive provided by sphinxcontrib.luadomain:

https://github.com/boolangery/sphinx-luadomain#available-sphinx-directives

Showing original source code

You can display method source code appending the flag show-source:

.. lua:autoclass:: pl.List:show-source:

Showing private members

By default, private members are hidden. You can display them by using the flag private-members:

.. lua:autoclass:: pl.List:private-members: