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'
    ]

# a list of lua source root
lua_source_path = ["../src/lua"]  # default is "./"

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.

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: