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

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

@@ -2,6 +2,39 @@
 
 ## [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
+  for `lua_ls_project_root`.
+
+  Prior to this change, `lua_ls_project_root` was resolved relative to the directory
+  containing source `.rst` files. Documentation, however, was saying that it's resolved
+  relative to the directory with `conf.py`.
+
+  This is not an issue, because in most projects `conf.py` and source `.rst` files
+  are located in the same directory. Still, I've decided to be consistent with
+  other Sphinx extensions and use `confdir` instead of `srcdir`.
+
+  This is a breaking change, but I don't believe there are any projects that
+  use separate `confdir` and `srcdir` (the only reason to do this is if you're
+  hosting multiple documentation sites in the same repo.) For this reason,
+  this change is released as a minor version change.
+
 ## [3.3.0]
 
 - Added an option to extend list options (like `:exclude-members:`) without overriding
@@ -182,7 +215,9 @@ 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.3.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
 [3.1.0]: https://github.com/taminomara/sphinx-lua-ls/compare/v3.0.0...v3.1.0

{sphinx_lua_ls-3.3.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.3.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.3.0 → sphinx_lua_ls-3.5.0}/docs/source/autodoc.rst

@@ -16,10 +16,10 @@ can be slightly different:
       comments.
 
       When generating documentation for a module, Sphinx-LuaLs will include
-      all module's objects returned by `require`, as well as all types located
+      all module's objects returned by ``require``, as well as all types located
       in the same namespace.
 
-      That is, for module `meow`, it will list everything in the ``require("meow")``,
+      That is, for module ``meow``, it will list everything in the ``require("meow")``,
       as well as all classes, aliases, and enums that have prefix ``meow.*``.
 
       Thus, a typical Lua module will look like this:
@@ -165,8 +165,8 @@ can be slightly different:
                }
 
 
-Autodoc directive
------------------
+Autodoc directives
+------------------
 
 .. rst:directive:: .. lua:autoobject:: name
 
@@ -175,31 +175,31 @@ 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` is passed.
+      they are skipped even if :rst:dir:`members <lua:autoobject:members>` is passed.
 
       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.3.0 → sphinx_lua_ls-3.5.0}/docs/source/conf.py

@@ -12,6 +12,7 @@ release = version = sphinx_lua_ls.__version__
 
 extensions = [
     "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx",
     "sphinx_design",
     "sphinx_lua_ls",
     "myst_parser",
@@ -23,9 +24,14 @@ exclude_patterns = []
 primary_domain = "lua"
 default_role = "lua:obj"
 
-lua_ls_project_root = "../example"
+lua_ls_project_root = "example"
 lua_ls_backend = "emmylua"
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "sphinx": ("https://www.sphinx-doc.org/", None),
+}
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

{sphinx_lua_ls-3.3.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.3.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.3.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]
@@ -89,14 +103,14 @@ Settings
 .. py:data:: class_default_force_non_colon
    :type:
 
-   If `true`, Sphinx-LuaLs will remove ``self`` from class constructor's signature.
+   If ``True``, Sphinx-LuaLs will remove ``self`` from class constructor's signature.
 
    If using EmmyLua as lua analyzer, this option will be inferred from ``.emmyrc.json``.
 
 .. py:data:: class_default_force_return_self
    :type:
 
-   If `true`, Sphinx-LuaLs will replace class constructor's return type with ``self``.
+   If ``True``, Sphinx-LuaLs will replace class constructor's return type with ``self``.
 
    If using EmmyLua as lua analyzer, this option will be inferred from ``.emmyrc.json``.
 
@@ -109,7 +123,7 @@ Settings
    Can be either ``"5.1"``, ``"5.2"``, ``"5.3"``, ``"5.4"``, or ``"jit"``.
 
    By default, Sphinx-LuaLs will choose this setting
-   based on your `.emmyrc.json`/`.luarc.json` file.
+   based on your ``.emmyrc.json``/``.luarc.json`` file.
 
 .. py:data:: lua_ls_apidoc_roots
    :type: dict[str, str | dict[str, Any]]
@@ -165,7 +179,7 @@ Settings
       This option might not work correctly on case-insensitive file systems.
 
       It will generate a separate file for every member of a module;
-      if there are members that only differ in case (i.e. `Class` vs `class`),
+      if there are members that only differ in case (i.e. ``Class`` vs ``class``),
       one of them will overwrite the file for another.
 
       If you're on Windows, and you experience difficulties because of it,
@@ -215,7 +229,7 @@ Settings
 
    Default value is ``50``, which is suitable for most Sphinx themes.
 
-   Setting this value to `None` will cause signature formatter
+   Setting this value to ``None`` will cause signature formatter
    to use Sphinx's global setting ``maximum_signature_line_length``.
    If ``maximum_signature_line_length`` is also ``None``,
    signature wrapping will be disabled.

{sphinx_lua_ls-3.3.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.3.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.3.0'
-__version_tuple__ = version_tuple = (3, 3, 0)
+__version__ = version = '3.5.0'
+__version_tuple__ = version_tuple = (3, 5, 0)
 
-__commit_id__ = commit_id = 'g1682461d4'
+__commit_id__ = commit_id = 'ga93dbf791'