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 values
lua_source_path = ["./"]
lua_source_encoding = 'utf8'
lua_source_comment_prefix = '---'
lua_source_use_emmy_lua_syntax = True
lua_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.
--- @class MyOrg.Car
local cls = class()

--- @param foo number
function cls: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:

---@alias SourceFn fun():string|nil,string|nil

---@param callback SourceFn
local function some_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.
---@param self Class
---@param other Class
---@return boolean
function cls.__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)
---```
function display.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: