sphinx-lua-ls 3.4.0__tar.gz → 3.5.0__tar.gz

{sphinx_lua_ls-3.4.0 → sphinx_lua_ls-3.5.0}/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [unreleased]
 
+## [3.5.0]
+
+- Added `autodata`, `autoattribute`, `autoclass`, and other `auto*` directives.
+
+  They work like `autoobject`, but apply their doctype to the documented object
+  (if `!doctype` was set in source code, it shouldn't conflict with the used directive).
+
+  They also allow overriding object's signature, which may be useful when
+  automatically generated signature is too long.
+
+- Added `lua_ls_max_version` config option to safeguard against incompatible changes
+  to documentation export format.
+
+- Fixed a few more minor bugs in highlighting of Lua types.
+
 ## [3.4.0]
 
 - **Potential breaking change:** use `confdir` instead of `srcdir` as base path
@@ -200,7 +215,8 @@ use `!doctype table` instead, otherwise you'll get errors that modules are not a
 
 Initial release.
 
-[unreleased]: https://github.com/taminomara/sphinx-lua-ls/compare/v3.4.0...HEAD
+[unreleased]: https://github.com/taminomara/sphinx-lua-ls/compare/v3.5.0...HEAD
+[3.5.0]: https://github.com/taminomara/sphinx-lua-ls/compare/v3.4.0...v3.5.0
 [3.4.0]: https://github.com/taminomara/sphinx-lua-ls/compare/v3.3.0...v3.4.0
 [3.3.0]: https://github.com/taminomara/sphinx-lua-ls/compare/v3.2.0...v3.3.0
 [3.2.0]: https://github.com/taminomara/sphinx-lua-ls/compare/v3.1.0...v3.2.0

{sphinx_lua_ls-3.4.0/sphinx_lua_ls.egg-info → sphinx_lua_ls-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-lua-ls
-Version: 3.4.0
+Version: 3.5.0
 Summary: Automatic documentation generation via EmmyLua/LuaLs
 Author-email: Tamika Nomara <taminomara@gmail.com>
 License-Expression: MIT

{sphinx_lua_ls-3.4.0 → sphinx_lua_ls-3.5.0}/docs/source/autodoc.rst

@@ -165,8 +165,8 @@ can be slightly different:
                }
 
 
-Autodoc directive
------------------
+Autodoc directives
+------------------
 
 .. rst:directive:: .. lua:autoobject:: name
 
@@ -175,14 +175,14 @@ Autodoc directive
    :rst:dir:`lua:autoobject` supports same settings as other lua directives,
    as well as some additional ones:
 
-   .. rst:directive:option:: members
+   .. rst:directive:option:: members: [<name>, ...]
 
       If enabled, autodoc will also document object's members. You can pass a list
       of comma-separated names to specify which members should be documented.
       Otherwise, this option will document all public non-special members
       which have a description.
 
-   .. rst:directive:option:: undoc-members
+   .. rst:directive:option:: undoc-members: [<name>, ...]
 
       Include undocumented members to the object's description. By default,
       they are skipped even if :rst:dir:`members <lua:autoobject:members>` is passed.
@@ -190,16 +190,16 @@ Autodoc directive
       Accepts a comma-separated list of names; if list is empty,
       adds all undoc members.
 
-   .. rst:directive:option:: private-members
-                             protected-members
-                             package-members
+   .. rst:directive:option:: private-members: [<name>, ...]
+                             protected-members: [<name>, ...]
+                             package-members: [<name>, ...]
 
       Include non-public members to the object's description.
 
       Accepts a comma-separated list of names; if list is empty,
       adds all non-public members.
 
-   .. rst:directive:option:: special-members
+   .. rst:directive:option:: special-members: [<name>, ...]
 
       Include members whose names start with double underscore
       to the object's description.
@@ -207,25 +207,25 @@ Autodoc directive
       Accepts a comma-separated list of names; if list is empty,
       adds all special members.
 
-   .. rst:directive:option:: inherited-members
+   .. rst:directive:option:: inherited-members: [<name>, ...]
 
       For classes, include members inherited from base classes.
 
       Accepts a comma-separated list of names; if list is empty,
       adds all inherited members.
 
-   .. rst:directive:option:: exclude-members
+   .. rst:directive:option:: exclude-members: [<name>, ...]
 
       A comma-separated list of members that should not be documented.
 
-   .. rst:directive:option:: globals
+   .. rst:directive:option:: globals: [<name>, ...]
 
       Will include global variables declared in the corresponding module.
 
       Accepts a comma-separated list of names; if list is empty,
       adds all global variables.
 
-   .. rst:directive:option:: class-doc-from
+   .. rst:directive:option:: class-doc-from: class | ctor | both | separate
 
       Specifies how to generate documentation for classes
       if :py:data:`class_default_function_name` is configured.
@@ -242,7 +242,7 @@ Autodoc directive
       - ``separate``: only use documentation from ``@class`` annotation,
         document class constructor as a separate method.
 
-   .. rst:directive:option:: class-signature
+   .. rst:directive:option:: class-signature: bases | ctor | both | minimal
 
       Specifies how to generate signatures for classes
       if :py:data:`class_default_function_name` is configured.
@@ -302,7 +302,7 @@ Autodoc directive
       (see :py:data:`lua_ls_default_options` for info on ``+``
       and overriding defaults).
 
-   .. rst:directive:option:: member-order
+   .. rst:directive:option:: member-order: alphabetical | groupwise | bysource
 
       Controls how members are sorted. There are three options available:
 
@@ -314,11 +314,11 @@ Autodoc directive
       - ``bysource``: members are sorted in the same order as they appear in code.
         This is the default option.
 
-   .. rst:directive:option:: module-member-order
+   .. rst:directive:option:: module-member-order: alphabetical | groupwise | bysource
 
       Overrides :rst:dir:`lua:autoobject:member-order` for modules.
 
-   .. rst:directive:option:: title
+   .. rst:directive:option:: title: <text>
 
       For modules, controls whether a title is inserted between module description
       and documentation of its members.
@@ -327,7 +327,7 @@ Autodoc directive
 
       Adds :rst:dir:`lua:autoindex` to the toplevel module.
 
-   .. rst:directive:option:: index-title
+   .. rst:directive:option:: index-title: <text>
 
       Allows overriding title of the :rst:dir:`lua:autoindex` section.
 
@@ -335,7 +335,7 @@ Autodoc directive
 
       Adds :rst:dir:`lua:other-inherited-members` to all classes.
 
-   .. rst:directive:option:: annotate-require
+   .. rst:directive:option:: annotate-require: always | never | auto | force
 
       Adds information about how to require a module.
 
@@ -355,16 +355,51 @@ Autodoc directive
 
          LuaLs only supports ``never`` and ``force``.
 
-   .. rst:directive:option:: require-function-name
+   .. rst:directive:option:: require-function-name: <name>
 
       Allows overriding name of the `require` function
       for :rst:dir:`lua:autoobject:annotate-require`.
 
-   .. rst:directive:option:: require-separator
+   .. rst:directive:option:: require-separator: <str>
 
       Allows overriding separator
       for :rst:dir:`lua:autoobject:annotate-require`.
 
+.. rst:directive:: .. lua:auto*::
+
+   In addition to :rst:dir:`lua:autoobject`, there are ``lua:autodata``,
+   ``lua:autoattribute``, ``lua:autoclass``, and other ``lua:auto*`` directives.
+
+   They work like ``lua:autoobject``, but apply their doctype to the documented object
+   (if ``!doctype`` was :ref:`set in source code <doc_comments>`,
+   it shouldn't conflict with the used directive).
+
+   They also allow overriding object's signature, which may be useful when
+   automatically generated signature is too long:
+
+   .. tab-set::
+      :sync-group: lang
+
+      .. tab-item:: RST
+         :sync: rst
+
+         .. code-block:: rst
+
+            .. lua:autofunction:: logging.getLogger(name: string?): logging.Logger
+
+      .. tab-item:: Markdown
+         :sync: md
+
+         .. code-block:: myst
+
+            ```{lua:autofunction} logging.getLogger(name: string? = ...): logging.Logger
+            ```
+
+   .. dropdown:: Example output
+
+      .. lua:autofunction:: logging.getLogger(name: string? = ...): logging.Logger
+         :no-index:
+
 .. rst:directive:: .. lua:autoindex:: module-name
 
    Creates a table that references all documented objects in the module ``module-name``.
@@ -387,6 +422,7 @@ Autodoc directive
    If given, class name must be absolute, even if this directive appears after
    :rst:dir:`lua:module`.
 
+.. _doc_comments:
 
 Controlling generation from code comments
 -----------------------------------------

{sphinx_lua_ls-3.4.0 → sphinx_lua_ls-3.5.0}/docs/source/directives.rst

@@ -283,10 +283,13 @@ Parameters
 All directives that document Lua objects accept the standard parameters:
 
 .. rst:directive:option:: no-index
+                          no-index-entry
+                          no-contents-entry
+                          no-typesetting
 
-   Render the documentation, but don't add it to the index
-   and don't create anchors. You will not be able to reference
-   un-indexed objects.
+    The `standard Sphinx options`__ available to all object descriptions.
+
+    __ https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup
 
 .. rst:directive:option:: private
                           protected
@@ -329,7 +332,7 @@ All directives that document Lua objects accept the standard parameters:
 
          Fetches content from the given url.
 
-.. rst:directive:option:: annotation
+.. rst:directive:option:: annotation: <text>
 
    Allows adding custom short annotations.
 
@@ -384,12 +387,12 @@ All directives that document Lua objects accept the standard parameters:
 
             Use ``name`` and ``surname`` instead.
 
-.. rst:directive:option:: synopsis
+.. rst:directive:option:: synopsis: <text>
 
    Allows adding a small description that's reflected
    in the :rst:dir:`lua:autoindex` output.
 
-.. rst:directive:option:: module
+.. rst:directive:option:: module: <name>
 
    Allows overriding current module for a single object. This is useful
    for documenting global variables that are declared in a module.

{sphinx_lua_ls-3.4.0 → sphinx_lua_ls-3.5.0}/docs/source/example/logging.lua

@@ -58,4 +58,10 @@ function logging.Logger:warning(msg, ...) end
 --- @param ... any parameters for message formatting.
 function logging.Logger:error(msg, ...) end
 
+--- Get logger with the given name, or create one if it doesn't exist.
+---
+--- @param name string? logger name. Uses current module name if empty.
+--- @return Logger logger logger with the given name.
+function logging.getLogger(name) end
+
 return logging

{sphinx_lua_ls-3.4.0 → sphinx_lua_ls-3.5.0}/docs/source/settings.rst

@@ -36,7 +36,21 @@ Settings
 .. py:data:: lua_ls_min_version
    :type: str
 
-   Controls the minimal version of the used lua analyzer.
+   Controls the minimum version of the used lua analyzer.
+
+   Analyzer version should be greater than or equal to this version.
+
+   For LuaLs, default value is ``3.0.0``, for EmmyLua it's ``0.11.0``.
+
+.. py:data:: lua_ls_max_version
+   :type: str | None
+
+   Controls the maximum version of the used lua analyzer.
+
+   Analyzer version should be strictly less than this version.
+
+   For LuaLs, default value is ``4.0.0``, for EmmyLua it's ``2.0.0``.
+   Use ``None`` to allow any version.
 
 .. py:data:: lua_ls_default_options
    :type: dict[str, str]

{sphinx_lua_ls-3.4.0 → sphinx_lua_ls-3.5.0}/sphinx_lua_ls/__init__.py

@@ -64,12 +64,19 @@ def run_lua_ls(app: sphinx.application.Sphinx):
             min_version = "3.0.0"
         else:
             min_version = "0.11.0"
+    max_version = domain.config.max_version
+    if max_version == "__auto__":
+        if domain.config.backend == "luals":
+            max_version = "4.0.0"
+        else:
+            max_version = "2.0.0"
 
     cwd = pathlib.Path.cwd()
     try:
         runner = sphinx_lua_ls.lua_ls.resolve(
             backend=domain.config.backend,
             min_version=min_version,
+            max_version=max_version,
             cwd=root_dir,
             reporter=sphinx_lua_ls.lua_ls.SphinxProgressReporter(app.verbosity),
             install=domain.config.auto_install,
@@ -187,6 +194,7 @@ def setup(app: sphinx.application.Sphinx):
     app.add_config_value("lua_ls_auto_install", True, rebuild="")
     app.add_config_value("lua_ls_auto_install_location", None, rebuild="")
     app.add_config_value("lua_ls_min_version", None, rebuild="env")
+    app.add_config_value("lua_ls_max_version", "__auto__", rebuild="env")
     app.add_config_value("lua_ls_lua_version", None, rebuild="html")
     app.add_config_value("lua_ls_default_options", None, rebuild="env")
     app.add_config_value("lua_ls_apidoc_roots", None, rebuild="")
@@ -203,6 +211,42 @@ def setup(app: sphinx.application.Sphinx):
     app.add_directive_to_domain(
         "lua", "autoobject", sphinx_lua_ls.autodoc.AutoObjectDirective
     )
+    app.add_directive_to_domain(
+        "lua", "autofunction", sphinx_lua_ls.autodoc.AutoFunctionDirective
+    )
+    app.add_directive_to_domain(
+        "lua", "autodata", sphinx_lua_ls.autodoc.AutoDataDirective
+    )
+    app.add_directive_to_domain(
+        "lua", "autoconst", sphinx_lua_ls.autodoc.AutoConstDirective
+    )
+    app.add_directive_to_domain(
+        "lua", "autoclass", sphinx_lua_ls.autodoc.AutoClassDirective
+    )
+    app.add_directive_to_domain(
+        "lua", "autoalias", sphinx_lua_ls.autodoc.AutoAliasDirective
+    )
+    app.add_directive_to_domain(
+        "lua", "autoenum", sphinx_lua_ls.autodoc.AutoEnumDirective
+    )
+    app.add_directive_to_domain(
+        "lua", "automethod", sphinx_lua_ls.autodoc.AutoMethodDirective
+    )
+    app.add_directive_to_domain(
+        "lua", "autoclassmethod", sphinx_lua_ls.autodoc.AutoClassmethodDirective
+    )
+    app.add_directive_to_domain(
+        "lua", "autostaticmethod", sphinx_lua_ls.autodoc.AutoStaticmethodDirective
+    )
+    app.add_directive_to_domain(
+        "lua", "autoattribute", sphinx_lua_ls.autodoc.AutoAttributeDirective
+    )
+    app.add_directive_to_domain(
+        "lua", "autotable", sphinx_lua_ls.autodoc.AutoTableDirective
+    )
+    app.add_directive_to_domain(
+        "lua", "automodule", sphinx_lua_ls.autodoc.AutoModuleDirective
+    )
     app.add_directive_to_domain(
         "lua", "autoindex", sphinx_lua_ls.autoindex.AutoIndexDirective
     )

{sphinx_lua_ls-3.4.0 → sphinx_lua_ls-3.5.0}/sphinx_lua_ls/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '3.4.0'
-__version_tuple__ = version_tuple = (3, 4, 0)
+__version__ = version = '3.5.0'
+__version_tuple__ = version_tuple = (3, 5, 0)
 
-__commit_id__ = commit_id = 'g02703ee01'
+__commit_id__ = commit_id = 'ga93dbf791'