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:
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.4-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c578d2911bc1395ef701e367cf2314abdc6bde3c6270b58f90a48927b29f0771 |
|
MD5 | 1c8f9b378424adf8518716a434faa482 |
|
BLAKE2b-256 | d50aca9fac2c42ed853804d8925af34ba30be7c400fce3c49eaa8c15e856cff4 |