sphinx-lua 1.1.5__tar.gz → 1.2.1__tar.gz

{sphinx-lua-1.1.5 → sphinx_lua-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sphinx-lua
-Version: 1.1.5
+Version: 1.2.1
 Summary: Support for using Sphinx on Luadoc-documented Lua code
 Author: Eliott Dumeix
 Author-email: eliott.dumeix@gmail.com
@@ -9,12 +9,20 @@ 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.5
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
+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
@@ -114,6 +122,59 @@ The following directives are available:
 
     .. 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``:
 

sphinx-lua-1.1.5/sphinx_lua.egg-info/PKG-INFO → sphinx_lua-1.2.1/README.rst

@@ -1,21 +1,3 @@
-Metadata-Version: 2.1
-Name: sphinx-lua
-Version: 1.1.5
-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.5
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Topic :: Documentation :: Sphinx
-Classifier: Topic :: Software Development :: Documentation
-License-File: LICENSE.txt
-
 ###############################################################################
 sphinx-lua
 ###############################################################################
@@ -114,6 +96,59 @@ The following directives are available:
 
     .. 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``:
 
@@ -139,4 +174,4 @@ By default, private members are hidden. You can display them by using the flag `
 .. code-block:: rst
 
     .. lua:autoclass:: pl.List
-        :private-members:
+        :private-members:

sphinx_lua-1.2.1/pyproject.toml

@@ -0,0 +1,7 @@
+[build-system]
+# setuptools>=70 emits Metadata-Version 2.4, which the pypa/gh-action-pypi-publish
+# release action (pinned in .github/workflows/python-publish.yml) fails to parse
+# ("Metadata is missing required fields: Name, Version") even though it is
+# present -- it's a parser mismatch, not actually missing metadata.
+requires = ["setuptools>=61,<70", "wheel"]
+build-backend = "setuptools.build_meta"

{sphinx-lua-1.1.5 → sphinx_lua-1.2.1}/setup.py

@@ -27,23 +27,26 @@ setup(
     license='MIT',
     license_files=('LICENSE.txt',),
     packages=find_packages(exclude=['ez_setup']),
-    test_suite='nose.collector',
     include_package_data=True,
     install_requires=[
-        'six',
         'Jinja2>3.0',
-        'luadoc>=1.3.1',
-        'sphinxcontrib-luadomain>=1.1.1'
+        'luadoc>=1.4.1',
+        'sphinxcontrib-luadomain>=1.2.0'
     ],
+    extras_require={
+        'test': ['pytest', 'Sphinx'],
+    },
     classifiers=[
         'Intended Audience :: Developers',
         'Natural Language :: English',
         'License :: OSI Approved :: MIT License',
-        'Programming Language :: Python :: 3.5',
-        'Programming Language :: Python :: 3.6',
-        'Programming Language :: Python :: 3.7',
+        'Programming Language :: Python :: 3.9',
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
+        'Programming Language :: Python :: 3.12',
         'Topic :: Documentation :: Sphinx',
         'Topic :: Software Development :: Documentation'
     ],
+    python_requires='>=3.9',
     keywords=['sphinx', 'documentation', 'docs', 'lua', 'luadoc', 'restructured'],
 )

{sphinx-lua-1.1.5 → sphinx_lua-1.2.1}/sphinx_lua/__init__.py

@@ -1,8 +1,10 @@
 from .directives import (auto_class_directive_bound_to_app,
                          auto_function_directive_bound_to_app,
                          auto_module_directive_bound_to_app,
-                         auto_class_summary_directive_bound_to_app)
+                         auto_class_summary_directive_bound_to_app,
+                         auto_alias_directive_bound_to_app)
 from .luadoc import run_luadoc
+from . import version
 
 
 def setup(app):
@@ -25,6 +27,9 @@ def setup(app):
     app.add_directive_to_domain('lua',
                                 'autoclasssummary',
                                 auto_class_summary_directive_bound_to_app(app))
+    app.add_directive_to_domain('lua',
+                                'autoalias',
+                                auto_alias_directive_bound_to_app(app))
     # TODO: We could add a lua:module with app.add_directive_to_domain().
 
     app.add_config_value('lua_source_path', ['./'], 'env')
@@ -34,6 +39,12 @@ def setup(app):
     app.add_config_value('lua_source_private_prefix', '_', 'env')
     app.add_config_value('luadoc_config_path', None, 'env')
 
+    return {
+        'version': version.__version__,
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
+
 
 def read_all_docs(app, env, doc_names):
     """Add all found docs to the to-be-read list, because we have no way of

{sphinx-lua-1.1.5 → sphinx_lua-1.2.1}/sphinx_lua/directives.py

@@ -10,7 +10,8 @@ can access each other and collaborate.
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst.directives import flag
 
-from .renderers import AutoFunctionRenderer, AutoClassRenderer, AutoModuleRenderer, AutoClassSummaryRenderer
+from .renderers import (AutoFunctionRenderer, AutoClassRenderer, AutoModuleRenderer, AutoClassSummaryRenderer,
+                        AutoAliasRenderer)
 
 
 class LuaDirective(Directive):
@@ -103,6 +104,21 @@ def auto_class_summary_directive_bound_to_app(app):
     return AutoClassSummaryDirective
 
 
+def auto_alias_directive_bound_to_app(app):
+    class AutoAliasDirective(LuaDirective):
+        """lua:autoalias directive, which spits out a lua:alias directive
+
+        Takes a single argument which is the name of an ``@alias``-declared
+        type.
+
+        """
+
+        def run(self):
+            return AutoAliasRenderer.from_directive(self, app).rst_nodes()
+
+    return AutoAliasDirective
+
+
 def _members_to_exclude(arg):
     """Return a set of members to exclude given a comma-delim list them.
 

{sphinx-lua-1.1.5 → sphinx_lua-1.2.1}/sphinx_lua/luadoc.py

@@ -10,6 +10,10 @@ def run_luadoc(app):
 
     modules = []
     for source_dir in app.config.lua_source_path:
+        # Resolve relative to confdir, not the process cwd: the build can be
+        # invoked from anywhere (e.g. `sphinx-build docs docs/_build` from a
+        # repo root, or programmatically), not just from inside confdir.
+        source_dir = os.path.join(app.confdir, source_dir)
         logger.debug('building lua documentation model for source dir: ' + source_dir)
 
         filenames = []
@@ -19,7 +23,7 @@ def run_luadoc(app):
         else:
             for root, subdirs, files in os.walk(source_dir):
                 for filename in files:
-                    if filename.endswith('lua'):
+                    if filename.endswith(('lua', 'luadoc')):
                         filepath = os.path.join(root, filename)
                         filenames.append(filepath)
 

{sphinx-lua-1.1.5 → sphinx_lua-1.2.1}/sphinx_lua/renderers.py

@@ -1,5 +1,3 @@
-from collections import OrderedDict
-from json import dumps
 import re
 import os
 
@@ -7,14 +5,23 @@ from docutils.parsers.rst import Parser as RstParser
 from docutils.statemachine import StringList
 from docutils.utils import new_document
 from jinja2 import Environment, PackageLoader
-from six import iteritems, string_types
 from sphinx.errors import SphinxError
-from sphinx.util import rst
 
 from sphinx.util import logging
 
 logger = logging.getLogger(__name__)
 
+# Mirrors sphinxcontrib.luadomain.KNOWN_LUA_METAMETHODS (Lua 5.4 manual,
+# section 2.4). Must stay in sync: luadomain's lua:metamethod directive warns
+# (an error under -W) on any name outside this list.
+KNOWN_LUA_METAMETHODS = frozenset([
+    '__add', '__sub', '__mul', '__div', '__mod', '__pow', '__unm', '__idiv',
+    '__band', '__bor', '__bxor', '__bnot', '__shl', '__shr',
+    '__concat', '__len', '__eq', '__lt', '__le',
+    '__index', '__newindex', '__call',
+    '__gc', '__close', '__mode', '__name',
+])
+
 
 class LuaRenderer(object):
     """Abstract superclass for renderers of various sphinx-lua directives
@@ -77,47 +84,81 @@ class LuaRenderer(object):
             """A non-optimal implementation of a regex filter"""
             return re.sub(r'@{\s*([\w.]*)\s*}', r':lua:class:`\1`', s)
 
+        def render_code_fences(s):
+            """Turn Markdown fenced code blocks (```lang\\ncode\\n```), as
+            commonly found in EmmyLua doc comments, into RST code-block
+            directives so they render instead of showing up as literal text.
+
+            """
+            def repl(match):
+                language = match.group(1) or 'lua'
+                code = match.group(2)
+                indented = '\n'.join('    ' + line if line.strip() else ''
+                                     for line in code.splitlines())
+                return '\n\n.. code-block:: %s\n\n%s\n\n' % (language, indented)
+
+            return re.sub(r'```(\w*)\n(.*?)```', repl, s, flags=re.DOTALL)
+
+        def link_custom_type(name):
+            """Turn a custom type name into a cross-reference if it matches a
+            known class or alias, so params/returns using ``@alias``-defined
+            types link to their definition. Falls back to plain text for
+            unknown names to avoid emitting dangling cross-references.
+
+            """
+            for module in getattr(self._app, '_sphinxlua_modules', []):
+                for alias in getattr(module, 'aliases', []):
+                    if alias.name == name:
+                        return ':lua:alias:`%s`' % name
+                for cls in module.classes:
+                    if cls.name == name:
+                        return ':lua:class:`%s`' % name
+            return name
+
         def start_stop_line(doc_node, file_path):
             """ Return start stop line in the form '1-5' """
-            file = open(os.path.join(self._app.confdir, file_path), "r")
-            start_line = file.read(doc_node.start_char).count('\n') + 1
-            stop_line = file.read(doc_node.stop_char - doc_node.start_char).count('\n') + 1 + start_line
-            file.close()
+            file_path = os.path.join(self._app.confdir, file_path)
+            with open(file_path, "r") as f:
+                content = f.read()
+            total_lines = content.count('\n') + 1
+            start_line = content[:doc_node.start_char].count('\n') + 1
+            stop_line = content[:doc_node.stop_char].count('\n') + 1
+            # Clamp to actual file line count (avoid "out of range" with Sphinx -W)
+            stop_line = min(stop_line, total_lines)
             return str(start_line) + "-" + str(stop_line)
 
         # Render to RST using Jinja:
         env = Environment(loader=PackageLoader('sphinx_lua', 'templates'))
         env.filters['process_link'] = process_link
+        env.filters['link_custom_type'] = link_custom_type
+        env.filters['render_code_fences'] = render_code_fences
         env.filters['start_stop_line'] = start_stop_line
+        env.tests['metamethod'] = lambda name: name in KNOWN_LUA_METAMETHODS
         template = env.get_template(self._template)
         return template.render(**args_dict)
 
-    def _name(self):
-        """Return the LUA function or class longname."""
-        return self._arguments[0].split('(')[0]
+class AutoFunctionRenderer(LuaRenderer):
+    _template = 'function.rst'
 
-    def _fields(self, doclet):
-        """Return an iterable of "info fields" to be included in the directive,
-        like params, return values, and exceptions.
+    def rst_nodes(self):
+        """Render a global (non-method, non-static) LUA function."""
+        lua_function = None
 
-        Each field consists of a tuple ``(heads, tail)``, where heads are
-        words that go between colons (as in ``:param string href:``) and
-        tail comes after.
+        for module in self._app._sphinxlua_modules:
+            for func in module.functions:
+                if func.name == self._partial_path:
+                    lua_function = func
+                    break
 
-        """
-        FIELD_TYPES = OrderedDict([('params', _params_formatter),
-                                   ('properties', _params_formatter),
-                                   ('exceptions', _exceptions_formatter),
-                                   ('returns', _returns_formatter)])
-        for field_name, callback in iteritems(FIELD_TYPES):
-            for field in doclet.get(field_name, []):
-                description = field.get('description', '')
-                unwrapped = re.sub(r'[ \t]*[\r\n]+[ \t]*', ' ', description)
-                yield callback(field, unwrapped)
+        if not lua_function:
+            raise SphinxError('No LUADoc documentation was found for object "%s" or any path ending with that.'
+                              % self._partial_path)
 
+        rst = self.rst(dict(function=lua_function))
+        doc = new_document('%s' % self._partial_path, settings=self._directive.state.document.settings)
 
-class AutoFunctionRenderer(LuaRenderer):
-    _template = 'function.rst'
+        RstParser().parse(rst, doc)
+        return doc.children
 
 
 class AutoClassRenderer(LuaRenderer):
@@ -157,6 +198,30 @@ class AutoClassRenderer(LuaRenderer):
         return doc.children
 
 
+class AutoAliasRenderer(LuaRenderer):
+    _template = 'alias.rst'
+
+    def rst_nodes(self):
+        """Render an ``@alias``-declared type as a ``lua:alias`` directive."""
+        lua_alias = None
+
+        for module in self._app._sphinxlua_modules:
+            for alias in getattr(module, 'aliases', []):
+                if alias.name == self._partial_path:
+                    lua_alias = alias
+                    break
+
+        if not lua_alias:
+            raise SphinxError('No LUADoc documentation was found for object "%s" or any path ending with that.'
+                              % self._partial_path)
+
+        rst = self.rst(dict(model=lua_alias))
+        doc = new_document('%s' % self._partial_path, settings=self._directive.state.document.settings)
+
+        RstParser().parse(rst, doc)
+        return doc.children
+
+
 class AutoModuleRenderer(LuaRenderer):
     _template = 'module.rst'
 
@@ -166,25 +231,29 @@ class AutoModuleRenderer(LuaRenderer):
 
         Fill in args, docstrings, and info fields from stored LUADoc output.
 
+        An exact module name is looked up first. If none matches, the argument
+        is treated as a regex pattern and every module whose name matches it is
+        rendered, allowing e.g. ``.. lua:automodule:: .*`` to document every
+        module found in ``lua_source_path`` in one shot.
+
         """
-        lua_module = None
+        all_modules = self._app._sphinxlua_modules
 
-        # lookup for class
-        for module in self._app._sphinxlua_modules:
-            if module.name == self._partial_path:
-                lua_module = module
-                break
+        lua_modules = [m for m in all_modules if m.name == self._partial_path]
 
-        if not lua_module:
+        if not lua_modules:
+            pattern = re.compile(self._partial_path)
+            lua_modules = [m for m in all_modules if pattern.match(m.name)]
+
+        if not lua_modules:
             raise SphinxError('No LUADoc documentation was found for object "%s" or any path ending with that.'
                               % self._partial_path)
 
-        rst = self.rst(dict(
-            name=self._partial_path,
-            module=lua_module
-        ))
-        doc = new_document('%s' % self._partial_path, settings=self._directive.state.document.settings)
+        rst = '\n\n'.join(
+            self.rst(dict(name=lua_module.name, module=lua_module))
+            for lua_module in sorted(lua_modules, key=lambda m: m.name))
 
+        doc = new_document('%s' % self._partial_path, settings=self._directive.state.document.settings)
         RstParser().parse(rst, doc)
         return doc.children
 
@@ -218,50 +287,3 @@ class AutoClassSummaryRenderer(LuaRenderer):
 
         RstParser().parse(rst, doc)
         return doc.children
-
-
-def _returns_formatter(field, description):
-    """Derive heads and tail from ``@returns`` blocks."""
-    types = _or_types(field)
-    tail = ('**%s** -- ' % types) if types else ''
-    tail += description
-    return ['returns'], tail
-
-
-def _params_formatter(field, description):
-    """Derive heads and tail from ``@param`` blocks."""
-    heads = ['param']
-    types = _or_types(field)
-    if types:
-        heads.append(types)
-    heads.append(rst.escape(field['name']))
-    tail = description
-    return heads, tail
-
-
-def _exceptions_formatter(field, description):
-    """Derive heads and tail from ``@throws`` blocks."""
-    heads = ['throws']
-    types = _or_types(field)
-    if types:
-        heads.append(types)
-    tail = description
-    return heads, tail
-
-
-def _or_types(field):
-    """Return all the types in a doclet subfield like "params" or "returns"
-    with vertical bars between them, like "number|string".
-
-    ReST-escape the types.
-
-    """
-    return rst.escape('|'.join(field.get('type', {}).get('names', [])))
-
-
-def _dotted_path(segments):
-    """Convert a LUA object path (``['dir/', 'file/', 'class#',
-    'instanceMethod']``) to a dotted style that Sphinx will better index."""
-    segments_without_separators = [s[:-1] for s in segments[:-1]]
-    segments_without_separators.append(segments[-1])
-    return '.'.join(segments_without_separators)

sphinx_lua-1.2.1/sphinx_lua/templates/alias.rst

@@ -0,0 +1,3 @@
+.. lua:alias:: {{ model.name }} = {% with type=model.type %}{% include "type.rst" %}{% endwith %}
+
+{{ model.desc|render_code_fences|process_link if model.desc }}

{sphinx-lua-1.1.5 → sphinx_lua-1.2.1}/sphinx_lua/templates/class.rst

@@ -10,10 +10,10 @@
 {%- filter indent(width=4) %}
 
 {% if model.short_desc -%}
-{{ model.short_desc | process_link }}
+{{ model.short_desc | render_code_fences | process_link }}
 {% endif %}
 {% if model.desc -%}
-{{ model.desc | process_link }}
+{{ model.desc | render_code_fences | process_link }}
 {%- endif %}
 {% if model.usage %}
 **Usage:**

{sphinx-lua-1.1.5 → sphinx_lua-1.2.1}/sphinx_lua/templates/function.rst

@@ -1,12 +1,14 @@
 .. lua:function::
 {{- " " + function.name }}({%- include "param_list.rst" %})
+    {# reset stale module context when rendered outside automodule -#}
+    {% if not module %}:module:{%- endif %}
 {%- filter indent(width=4) %}
 
 {% if function.short_desc -%}
-{{ function.short_desc | process_link }}
+{{ function.short_desc | render_code_fences | process_link }}
 {% endif %}
 {% if function.desc -%}
-{{ function.desc | process_link }}
+{{ function.desc | render_code_fences | process_link }}
 {%- endif %}
 
 {% for param in function.params -%}

{sphinx-lua-1.1.5 → sphinx_lua-1.2.1}/sphinx_lua/templates/method.rst

@@ -1,4 +1,6 @@
-{%- if method.is_static -%}
+{%- if method.name is metamethod -%}
+.. lua:metamethod::
+{%- elif method.is_static -%}
 .. lua:staticmethod::
 {%- else -%}
 .. lua:method::
@@ -19,10 +21,10 @@
 {%- endif %}
 
 {% if method.short_desc -%}
-{{ method.short_desc | process_link }}
+{{ method.short_desc | render_code_fences | process_link }}
 {% endif %}
 {% if method.desc -%}
-{{ method.desc | process_link }}
+{{ method.desc | render_code_fences | process_link }}
 {%- endif %}
 
 {% for param in method.params -%}

{sphinx-lua-1.1.5 → sphinx_lua-1.2.1}/sphinx_lua/templates/module.rst

@@ -1,8 +1,8 @@
 .. lua:module:: {{ module.name }}
 
-{{ module.short_desc|process_link if module.short_desc }}
+{{ module.short_desc|render_code_fences|process_link if module.short_desc }}
 
-{{ module.desc|process_link if module.desc }}
+{{ module.desc|render_code_fences|process_link if module.desc }}
 
 {% if module.usage -%}
 **Usage:**
@@ -13,6 +13,12 @@
     {{ module.usage|indent(4) }}
 {%- endif %}
 
+{% for alias in module.aliases %}
+{% with model=alias %}
+{% include "alias.rst" %}
+{% endwith %}
+{% endfor %}
+
 {% for function in module.functions %}
 {% include "function.rst" %}
 {% endfor %}

{sphinx-lua-1.1.5 → sphinx_lua-1.2.1}/sphinx_lua/templates/type.rst

@@ -17,7 +17,7 @@
 {%- elif type.id == "nil" -%}
     nil
 {%- elif type.id == "custom" -%}
-    {{ type.name }}
+    {{ type.name|link_custom_type }}
 {%- elif type.id == "or" -%}
 {% for type in type.types -%}
 {% include "type.rst" %}{{ " or " if not loop.last }}

sphinx_lua-1.2.1/sphinx_lua/version.py

@@ -0,0 +1 @@
+__version__ = '1.2.1'

sphinx-lua-1.1.5/README.rst → sphinx_lua-1.2.1/sphinx_lua.egg-info/PKG-INFO

@@ -1,3 +1,29 @@
+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
 ###############################################################################
@@ -96,6 +122,59 @@ The following directives are available:
 
     .. 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``:
 
@@ -121,4 +200,4 @@ By default, private members are hidden. You can display them by using the flag `
 .. code-block:: rst
 
     .. lua:autoclass:: pl.List
-        :private-members:
+        :private-members:

{sphinx-lua-1.1.5 → sphinx_lua-1.2.1}/sphinx_lua.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 LICENSE.txt
 MANIFEST.in
 README.rst
+pyproject.toml
 setup.cfg
 setup.py
 sphinx_lua/__init__.py
@@ -13,6 +14,7 @@ sphinx_lua.egg-info/SOURCES.txt
 sphinx_lua.egg-info/dependency_links.txt
 sphinx_lua.egg-info/requires.txt
 sphinx_lua.egg-info/top_level.txt
+sphinx_lua/templates/alias.rst
 sphinx_lua/templates/attribute.rst
 sphinx_lua/templates/class.rst
 sphinx_lua/templates/classsummary.rst

sphinx_lua-1.2.1/sphinx_lua.egg-info/requires.txt

@@ -0,0 +1,7 @@
+Jinja2>3.0
+luadoc>=1.4.1
+sphinxcontrib-luadomain>=1.2.0
+
+[test]
+pytest
+Sphinx

sphinx-lua-1.1.5/sphinx_lua/version.py

@@ -1 +0,0 @@
-__version__ = '1.1.5'

sphinx-lua-1.1.5/sphinx_lua.egg-info/requires.txt

@@ -1,4 +0,0 @@
-six
-Jinja2>3.0
-luadoc>=1.3.1
-sphinxcontrib-luadomain>=1.1.1