Metadata-Version: 2.1
Name: sphinx-lua
Version: 1.2.1
Summary: Support for using Sphinx on Luadoc-documented Lua code
Author: Eliott Dumeix
Author-email: eliott.dumeix@gmail.com
License: MIT
Keywords: sphinx,documentation,docs,lua,luadoc,restructured
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.9
License-File: LICENSE.txt
Requires-Dist: Jinja2>3.0
Requires-Dist: luadoc>=1.4.1
Requires-Dist: sphinxcontrib-luadomain>=1.2.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: Sphinx; extra == "test"

###############################################################################
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.

    .. lua:autoalias:: SourceFn


``automodule`` also accepts a regex, documenting every matching module in one
call, which is handy to generate the whole documentation for everything found
in ``lua_source_path``:

.. code-block:: rst

    .. lua:automodule:: .*


``@alias`` tags are rendered as ``lua:alias`` directives (either standalone via
``autoalias``, or automatically as part of ``automodule``'s output), and any
``@param``/``@return``/``@field`` referencing an alias or class by name is
turned into a link to its definition:

.. code-block:: lua

    ---@alias SourceFn fun():string|nil,string|nil

    ---@param callback SourceFn
    local function some_function(callback)
    end


A method whose name is a known Lua metamethod (``__index``, ``__eq``,
``__call``, etc., per the Lua 5.4 manual) is automatically rendered with
``lua:metamethod`` instead of ``lua:method``:

.. code-block:: lua

    ---Compare two instances for equality.
    ---@param self Class
    ---@param other Class
    ---@return boolean
    function cls.__eq(self, other)
    end


Markdown-style fenced code blocks (as commonly used in EmmyLua doc comments)
in descriptions are rendered as proper, syntax-highlighted code blocks:

.. code-block:: lua

    ---Returns 16-bit color.
    ---
    ---Example:
    ---```lua
    ---local color = display.color565(255, 0, 0)
    ---```
    function display.color565(r, g, b) end


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:


Showing private members
-------------------------------------------------------------------------------

By default, private members are hidden. You can display them by using the flag ``private-members``:

.. code-block:: rst

    .. lua:autoclass:: pl.List
        :private-members:
