###############################################################################
sphinx-lua
###############################################################################
.. image:: https://img.shields.io/pypi/v/sphinx-lua.svg
:target: https://pypi.python.org/pypi/sphinx-lua/
.. image:: https://img.shields.io/pypi/pyversions/sphinx-lua.svg
:target: https://pypi.python.org/pypi/sphinx-lua/
A lua-autodoc tool for Sphinx.
Generate a beautiful sphinx doc using lua doc comment.
It use `emmylua <https://emmylua.github.io/annotations/class.html>`_ as primary doc syntax but it is also
compatible with some `ldoc <https://stevedonovan.github.io/ldoc/manual/doc.md.html>`_ tags.
Installation
===============================================================================
.. code-block:: bash
$ 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:
.. code-block:: python
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:
.. code-block:: lua
--- 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:
.. code-block:: rst
.. 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:
.. code-block:: bash
$ luadoc ../src/lua/my_problematic_source_file.lua
Available sphinx directives
===============================================================================
The following directives are available:
.. code-block:: rst
.. 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``:
.. code-block:: rst
.. lua:autoclass:: pl.List
:show-source:
Raw data
{
"_id": null,
"home_page": "",
"name": "sphinx-lua",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "sphinx,documentation,docs,lua,luadoc,restructured",
"author": "Eliott Dumeix",
"author_email": "eliott.dumeix@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/3a/53/b16d9bd18fc993e3fba2ec816e1feed309d21d723b27ab980d9741166cb7/sphinx-lua-1.1.4.tar.gz",
"platform": null,
"description": "###############################################################################\nsphinx-lua\n###############################################################################\n\n.. image:: https://img.shields.io/pypi/v/sphinx-lua.svg\n :target: https://pypi.python.org/pypi/sphinx-lua/\n.. image:: https://img.shields.io/pypi/pyversions/sphinx-lua.svg\n :target: https://pypi.python.org/pypi/sphinx-lua/\n\nA lua-autodoc tool for Sphinx.\nGenerate a beautiful sphinx doc using lua doc comment.\n\nIt use `emmylua <https://emmylua.github.io/annotations/class.html>`_ as primary doc syntax but it is also\ncompatible with some `ldoc <https://stevedonovan.github.io/ldoc/manual/doc.md.html>`_ tags.\n\n\nInstallation\n===============================================================================\n\n.. code-block:: bash\n\n $ pip install sphinx-lua\n\nDependencies:\n\n * Jinja2 (to render rst template)\n * luadoc (to parse lua comments)\n * sphinxcontrib-luadomain (to add lua domain to sphinx)\n\n\nSphinx integration\n===============================================================================\n\nAdd the following to your conf.py:\n\n.. code-block:: python\n\n extensions = [\n 'sphinxcontrib.luadomain', \n 'sphinx_lua'\n ]\n \n # Available options and default values\n lua_source_path = [\"./\"]\n lua_source_encoding = 'utf8'\n lua_source_comment_prefix = '---'\n lua_source_use_emmy_lua_syntax = True\n lua_source_private_prefix = '_'\n\n \nThe ``lua_source_path`` configuration value tells to sphinx-lua where to find\nlua source code.\n\nWith above configuration, if `main.lua` is located in `../src/lua/main.lua`, and it's content\nis:\n\n.. code-block:: lua\n\n --- Define a car.\n --- @class MyOrg.Car\n local cls = class()\n\n --- @param foo number\n function cls:test(foo)\n end\n\nYou can autodoc it in sphinx with the following directive:\n\n.. code-block:: rst\n\n .. lua:autoclass:: MyOrg.Car\n\n\nTroubleshooting\n===============================================================================\n\nSphinx-lua use the documentation model extracted from luadoc (https://github.com/boolangery/py-lua-doc)\n\nSo you can print this model out using the command line tool:\n\n.. code-block:: bash\n\n $ luadoc ../src/lua/my_problematic_source_file.lua\n\n\nAvailable sphinx directives\n===============================================================================\n\nThe following directives are available:\n\n.. code-block:: rst\n\n .. lua:autoclass:: pl.List\n\n .. lua:automodule:: pl.stringx\n\n .. lua:autoclasssummary:: ^pl.\n\n\nYou can also use directive provided by ``sphinxcontrib.luadomain``:\n\nhttps://github.com/boolangery/sphinx-luadomain#available-sphinx-directives\n\n\nShowing original source code\n-------------------------------------------------------------------------------\n\nYou can display method source code appending the flag ``show-source``:\n\n.. code-block:: rst\n\n .. lua:autoclass:: pl.List\n :show-source:\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Support for using Sphinx on Luadoc-documented Lua code",
"version": "1.1.4",
"split_keywords": [
"sphinx",
"documentation",
"docs",
"lua",
"luadoc",
"restructured"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d50aca9fac2c42ed853804d8925af34ba30be7c400fce3c49eaa8c15e856cff4",
"md5": "1c8f9b378424adf8518716a434faa482",
"sha256": "c578d2911bc1395ef701e367cf2314abdc6bde3c6270b58f90a48927b29f0771"
},
"downloads": -1,
"filename": "sphinx_lua-1.1.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "1c8f9b378424adf8518716a434faa482",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 24022,
"upload_time": "2023-02-11T19:32:15",
"upload_time_iso_8601": "2023-02-11T19:32:15.123590Z",
"url": "https://files.pythonhosted.org/packages/d5/0a/ca9fac2c42ed853804d8925af34ba30be7c400fce3c49eaa8c15e856cff4/sphinx_lua-1.1.4-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3a53b16d9bd18fc993e3fba2ec816e1feed309d21d723b27ab980d9741166cb7",
"md5": "26eef1c7af21922b86b98cd4aa160c13",
"sha256": "e8cb3d5b8e3980043d43ca9e55a78ae565839c531f9116c01d5d2d85aff361ef"
},
"downloads": -1,
"filename": "sphinx-lua-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "26eef1c7af21922b86b98cd4aa160c13",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22476,
"upload_time": "2023-02-11T19:32:16",
"upload_time_iso_8601": "2023-02-11T19:32:16.786816Z",
"url": "https://files.pythonhosted.org/packages/3a/53/b16d9bd18fc993e3fba2ec816e1feed309d21d723b27ab980d9741166cb7/sphinx-lua-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-11 19:32:16",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "sphinx-lua"
}
JSON