Skip to main content

Support for using Sphinx on Luadoc-documented Lua code

Project description

https://img.shields.io/pypi/v/sphinx-lua.svg https://img.shields.io/pypi/pyversions/sphinx-lua.svg

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

sphinx-lua-1.1.5.tar.gz (22.7 kB view hashes)

Uploaded Source

Built Distribution

sphinx_lua-1.1.5-py2.py3-none-any.whl (24.3 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page