Support for using Sphinx on Luadoc-documented Lua code
Project description
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.
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:
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx_lua-1.1.5-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3c2a239f3a557cdffdcfd019f164304d6b7ff17add1d2d6b0a73a854dd06c402 |
|
MD5 | 3af4fcae2d4af592c860c600ba9d3dcb |
|
BLAKE2b-256 | b8c748bd9b32f27a07d1870d78aa24771324023e029fa9e7345b180413d69860 |