sphinx-lua-ls 1.0.0__tar.gz → 2.0.0__tar.gz

sphinx_lua_ls-2.0.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## v2.0.0
+
+- Breaking change: don't implicitly convert classes that're derived from `table`
+  to modules. Users should use a `!doctype` comment instead.
+- Breaking change: disallow nesting modules inside classes.
+- Added `autoindex` directive.
+- Added `apidoc` functionality.
+- Improved test coverage and fixed found bugs.
+
+**Migrating to 2.0.0:**
+
+In your Lua code base, perform global replace by regexp:
+
+```
+^(\s*)---\s*@class\s*(.+): table$
+```
+
+to
+
+```
+$1--- !doctype module
+$1--- @class $2
+```
+
+Make sure that you only use `!doctype module` on the top-level
+tables that can be imported via `require`. On other objects,
+use `!doctype table` instead, otherwise you'll get errors that modules are not allowed within other objects.
+
+## v1.1.0
+
+- Added support for `!doc` and `!doctype` comments.
+- Added `:include-protected:` and `:include-package:` options for `lua:autoobject`.
+- Allowed referring `lua:const` objects from `lua:attr` role.
+- Fixed a bug when default options would not properly propagate
+  when using `lua:autoobject` with `:recurse:`.
+- Fixed a bug when `lua:autoobject` would deduce incorrect module paths
+  when applied to non-toplevel modules.
+- Fixed a bug when docstring for a class would be used for undocumented function
+  parameters that have this class as their type.
+- Fixed types when `lua:autoobject` would infer incorrect types for `data`.
+
+## v1.0.0
+
+Initial release.

{sphinx_lua_ls-1.0.0/sphinx_lua_ls.egg-info → sphinx_lua_ls-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: sphinx-lua-ls
-Version: 1.0.0
+Version: 2.0.0
 Summary: Automatic documentation generation via LuaLS
 Author-email: Tamika Nomara <taminomara@gmail.com>
 License: MIT License
@@ -28,6 +28,7 @@ License: MIT License
 Project-URL: Documentation, https://taminomara.github.io/sphinx-lua-ls/
 Project-URL: Issues, https://github.com/taminomara/sphinx-lua-ls/issues
 Project-URL: Source, https://github.com/taminomara/sphinx-lua-ls/
+Project-URL: Changelog, https://github.com/taminomara/sphinx-lua-ls/blob/main/CHANGELOG.md
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3
@@ -63,7 +64,7 @@ Requires-Dist: pytest-regressions~=2.7; extra == "test"
 Requires-Dist: beautifulsoup4~=4.13; extra == "test"
 Provides-Extra: doc
 Requires-Dist: sybil~=6.1; extra == "doc"
-Requires-Dist: pydata-sphinx-theme>=0.15; extra == "doc"
+Requires-Dist: furo>=2024; extra == "doc"
 Requires-Dist: sphinx_design>=0.6; extra == "doc"
 
 # Sphinx plugin for Lua and Lua Language Server

{sphinx_lua_ls-1.0.0 → sphinx_lua_ls-2.0.0}/docs/example/logging.lua

@@ -3,7 +3,8 @@
 --- .. lua:autoobject:: LOG_LEVEL
 ---    :global:
 ---
---- @class logging: table
+--- !doctype module
+--- @class logging
 logging = {}
 
 --- Represents message severity.

{sphinx_lua_ls-1.0.0 → sphinx_lua_ls-2.0.0}/docs/source/conf.py

@@ -27,22 +27,10 @@ lua_ls_project_root = "../example"
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "pydata_sphinx_theme"
+html_theme = "furo"
 html_extra_path = ["_extra/robots.txt"]
 html_theme_options = {
-    "use_edit_page_button": True,
-    "icon_links": [
-        {
-            "name": "GitHub",
-            "url": "https://github.com/taminomara/sphinx-lua-ls",
-            "icon": "fa-brands fa-square-github",
-            "type": "fontawesome",
-        }
-   ]
-}
-html_context = {
-    "github_user": "taminomara",
-    "github_repo": "sphinx-lua-ls",
-    "github_version": "main",
-    "doc_path": "docs/source",
+    "source_repository": "https://github.com/taminomara/sphinx-lua-ls",
+    "source_branch": "main",
+    "source_directory": "docs/source",
 }

{sphinx_lua_ls-1.0.0 → sphinx_lua_ls-2.0.0}/docs/source/index.rst

@@ -127,6 +127,10 @@ and specify the location of your Lua project:
    # relative to the directory with `conf.py`.
    lua_ls_project_root = "../"
 
+If you plan to use Markdown in code comments, install the `MySt`_ plugin for Sphinx.
+
+.. _MySt: https://myst-parser.readthedocs.io/en/latest/index.html
+
 Quickstart
 ----------
 
@@ -220,6 +224,11 @@ Declaring objects
 
          Person's name.
 
+.. rst:directive:: .. lua:table:: name
+
+   Directive for documenting tables that serve as namespaces.
+   It works like :rst:dir:`data`, but can contain nested members.
+
 .. rst:directive:: .. lua:function:: name(param: type) -> type
                    .. lua:method:: name(param: type) -> type
                    .. lua:classmethod:: name(param: type) -> type
@@ -283,6 +292,9 @@ Declaring objects
 
    This directive doesn't accept any content, it just creates an anchor.
 
+   Modules are something you can `require`. If you need to document a namespace
+   inside of a module, use a :rst:dir:`lua:table` instead.
+
 .. rst:directive:: .. lua:currentmodule:: name
 
    Switches current module without making an index entry or an anchor.
@@ -365,6 +377,11 @@ All directives that document Lua objects accept the standard parameters:
 
             Use ``name`` and ``surname`` instead.
 
+.. rst:directive:option:: synopsis
+
+   Allows adding a small description that's reflected
+   in the :rst:dir:`lua:autoindex` output.
+
 .. rst:directive:option:: module
 
    Allows overriding current module for a single object. This is useful
@@ -439,44 +456,63 @@ Cross-referencing objects
 
       Reference to a `logging.Logger.info`.
 
-Autodoc directive
------------------
+Autodoc directives
+------------------
 
 .. rst:directive:: .. lua:autoobject:: name
 
    You can automatically generate documentation for any object by invoking
    the :rst:dir:`lua:autoobject` directive.
 
-   .. note::
+   Tables are exported as :rst:dir:`data` by default, meaning that their contents
+   are not documented.
 
-      Autodoc will parse object comments as ReStructured Text, not as MarkDown.
+   To enable documentation within a table, annotate is as a class.
+   You can change how autodoc infers its type by adding a ``!doctype`` comment.
 
-   .. note::
+   Thus, a typical Lua module will look like this:
 
-      Tables are exported as :rst:dir:`data` by default, meaning that their contents
-      are not documented.
+   .. code-block:: lua
 
-      To enable documentation within a table, document is as a class.
-      If you inherit it from `table`, autodoc will treat it as a module.
-      Thus, a typical Lua module will look like this:
+      --- This is a module. Notice that we've declared it as a class
+      --- and added a `doctype`.
+      ---
+      --- !doctype module
+      --- @class library
+      local library = {}
 
-      .. code-block:: lua
+      --- Nested namespaces should also be declared as classes.
+      ---
+      --- !doctype table
+      --- @class library.namespace
+      library.namespace = {}
+
+      --- Other objects are documented as usual.
+      function library.foo() end
+
+      --- And so on...
+      function library.namespace.bar() end
+
+      return library
+
+   .. note::
+
+      By default, autodoc will parse object comments as ReStructured Text,
+      not as MarkDown. If you plan to use Markdown in code comments,
+      install the `MySt`_ plugin for Sphinx and invoke include
+      :rst:dir:`lua:autoobject` from a markdown file.
 
-         --- This is a module. Notice that we've declared it as a class
-         --- inherited from `table`.
-         ---
-         --- @class library: table
-         local library = {}
+      Make sure to separate comment markers from documentation with a space.
+      Otherwise, autodoc will not be able to tell your comments apart from content
+      automatically generated by Lua Language Server:
 
-         --- Submodules should also be declared as classes.
-         ---
-         --- @class library.submodule: table
-         library.submodule = {}
+      .. code-block:: lua
 
-         --- Other objects are documented as usual.
-         function library.foo() end
+         --- This is OK: separated by a space.
+         local x = 0;
 
-         return library
+         ---This is NOT OK: no separation.
+         local x = 0;
 
    .. warning::
 
@@ -487,7 +523,7 @@ Autodoc directive
 
       2. ``@deprecated`` markers do not add any note to the documentation.
          We recommend providing an explicit message
-         with the :rst:dir:`deprecated` directive.
+         with the ``deprecated`` directive.
 
       3. ``@nodiscard`` and ``@operator`` markers are not exported.
 
@@ -498,13 +534,17 @@ Autodoc directive
 
             --- Instead of enums, we use aliases.
             ---
-            --- @alias LogLevel integer
-            LogLevel = {}
-
-            --- Alias members are declared as usual.
-            LogLevel.Debug = 1
-
+            --- .. lua:data:: Debug
+            ---
+            ---    Document alias members in its body.
+            ---
             --- And so on...
+            ---
+            --- @alias LogLevel integer
+            LogLevel = {
+               Debug = 1,
+               -- ...
+            }
 
    :rst:dir:`lua:autoobject` supports same settings as other lua directives,
    as well as some additional ones:
@@ -512,7 +552,7 @@ Autodoc directive
    .. rst:directive:option:: members
 
       If enabled, autodoc will also document object's members. You can pass a list
-      of coma-separated names to specify which members should be documented.
+      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.
 
@@ -521,22 +561,36 @@ Autodoc directive
       Include undocumented members to the object's description. By default,
       they are skipped even if :rst:dir:`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
 
       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
 
       Include special members to the object's description. That is, generate
       documentation for members whose names start with double underscore.
 
+      Accepts a comma-separated list of names; if list is empty,
+      adds all special members.
+
    .. rst:directive:option:: inherited-members
 
       For classes, includes 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
 
-      A coma-separated list of members that should not be documented.
+      A comma-separated list of members that should not be documented.
 
    .. rst:directive:option:: recursive
 
@@ -544,13 +598,20 @@ Autodoc directive
       for all objects nested within the root. That is, object's members,
       their members, and so on.
 
-      Settings for :rst:dir:undoc-members, :rst:dir:private-members,
-      :rst:dir:special-members, and :rst:dir:inherited-members are applied
-      to all documented objects.
+      If :rst:dir:`lua:autoobject:undoc-members`,
+      :rst:dir:`lua:autoobject:private-members`,
+      :rst:dir:`lua:autoobject:special-members`,
+      or :rst:dir:`lua:autoobject:inherited-members`
+      are given as flags, they are propagated to all documented objects.
+
+      If they're given as list, they are not propagated.
+
+      Options from :py:data:`lua_ls_default_options` are applied to all recursively
+      documented objects.
 
    .. rst:directive:option:: member-order
 
-      Controls how items are sorted. There are three options available:
+      Controls how members are sorted. There are three options available:
 
       - ``alphabetical``: members are sorted in lexicographical order of their names;
 
@@ -566,6 +627,98 @@ Autodoc directive
          for enums (``@enum``). If ordering by source, enums will be placed
          at the end of the documentation.
 
+   .. rst:directive:option:: module-member-order
+
+      Overrides :rst:dir:`lua:autoobject:member-order` for modules.
+
+   .. rst:directive:option:: title
+
+      For modules, controls whether a title is inserted between module description
+      and documentation of its members.
+
+   .. rst:directive:option:: index-table
+
+      Adds :rst:dir:`lua:autoindex` to the toplevel module.
+
+   .. rst:directive:option:: index-title
+
+      Allows overriding title of the :rst:dir:`lua:autoindex` section.
+
+.. rst:directive:: .. lua:autoindex:: name
+
+   Creates a table that references all documented objects in the module ``name``.
+   This is useful for creating module's table of contents.
+
+   Module name must be absolute, even if this directive appears after
+   :rst:dir:`lua:module`.
+
+Controlling generation from code comments
+-----------------------------------------
+
+When using :rst:dir:`lua:autoobject` in recursive mode, it is sometimes necessary
+to override its options for some objects. To do this, you can include specially
+formatted comments to your documentation.
+
+To override any :rst:dir:`lua:autoobject` setting for a particular object,
+use ``!doc`` comments. For example, here we enable :rst:dir:`lua:autoobject:special-members`
+and exclude ``__tostring`` for class ``Foo``:
+
+.. code-block:: lua
+
+   --- Some class documentation...
+   ---
+   --- !doc special-members
+   --- !doc exclude-members: __tostring
+   --- @class Foo
+
+You can also specify which type of object is being documented by using
+a ``!doctype`` comment. For example, here we use ``!doctype const`` to indicate
+that a certain variable should be documented as :rst:dir:`lua:const`:
+
+.. code-block:: lua
+
+   --- Some const documentation...
+   ---
+   --- !doctype const
+   --- @type string
+   foo = "bar!"
+
+.. _apidoc:
+
+Automatic API reference generation
+----------------------------------
+
+:rst:dir:`lua:autoobject` allows recursively generating documentation,
+however it all ends up on a single page. If you want to give a separate page
+for every module, you'll need to create multiple ``.rst`` files.
+Fortunately, Lua autodoc can do this for you.
+
+Add :py:data:`lua_ls_apidoc_roots` option to the ``conf.py``, and provide a mapping
+from module names to directories (relative to the location of ``conf.py``)
+where generated ``.rst`` files should be placed.
+
+For example, to generate API reference for module ``moduleName``
+in directory ``moduleDirectory``, add the following:
+
+.. code-block:: python
+
+   lua_ls_apidoc_roots = {
+       "moduleName": "moduleDirectory",
+   }
+
+Upon start, autodoc will recursively create ``.rst`` files in ``moduleDirectory``.
+``moduleDirectory/index.rst`` will contain reference for ``moduleName``.
+Then, for every submodule of ``moduleName``, there will be another ``.rst`` generated.
+
+.. warning::
+
+   Do not add any other files to ``moduleDirectory``, otherwise they will be deleted.
+
+   It is best to add ``moduleDirectory`` to your ``.gitignore`` file.
+
+Don't forget to include ``moduleDirectory/index.rst`` into a table of contents
+in your main ``index.rst``.
+
 Settings
 --------
 
@@ -606,12 +759,12 @@ Settings
    .. code-block:: python
 
       lua_ls_default_options = {
-         # Enable documentation for object's members.
-         # Empty string means documenting all members with non-empty description.
-         "members": "",
-         # Set ordering of automatically generated content to alphabetical.
-         "member-order": "alphabetical",
-         # And so on...
+          # Enable documentation for object's members.
+          # Empty string means documenting all members with non-empty description.
+          "members": "",
+          # Set ordering of automatically generated content to alphabetical.
+          "member-order": "alphabetical",
+          # And so on...
       }
 
 .. py:data:: lua_ls_lua_version: str
@@ -619,6 +772,61 @@ Settings
    Controls which documentation version is used when linking
    to standard library functions. Does not otherwise affect parsing or generation.
 
+.. py:data:: lua_ls_apidoc_roots: dict[str, str | dict[str, Any]]
+
+   Roots for `apidoc <automatic generation of API files>`_. Keys are full module names
+   that should be generated, and values are directories (relative to the location
+   of ``conf.py``) where ``.rst`` files are placed.
+
+   Additionally, you can override other apidoc settings for each root. For this,
+   make root's value a dictionary with keys ``path``,
+   :py:data:`max_depth <lua_ls_apidoc_max_depth>`,
+   :py:data:`options <lua_ls_apidoc_default_options>`,
+   and :py:data:`ignored_modules <lua_ls_apidoc_ignored_modules>`:
+
+   .. code-block:: python
+
+      lua_ls_apidoc_roots = {
+          "moduleName": {
+              "path": "moduleDirectory",
+              "max_depth": 2,
+              "options": {
+                  "undoc-members": "",
+              }
+          },
+      }
+
+.. py:data:: lua_ls_apidoc_default_options: dict[str, str]
+
+   Default options for objects documented via apidoc. Override
+   :py:data:`lua_ls_default_options`.
+
+.. py:data:: lua_ls_apidoc_max_depth: int
+
+   Maximum nesting level for files. Submodules that are deeper than this level
+   will not get their own file, and instead will be generated inline.
+
+   Default value is ``4``.
+
+.. py:data:: lua_ls_apidoc_ignored_modules: list[str]
+
+   List of full submodule names that should be ignored while generating APIs.
+   Submodules can contain :py:mod:`fnmatch` style globs.
+
+   For example, the following setting
+
+   .. code-block:: python
+
+      lua_ls_apidoc_roots = {
+          "moduleName": "moduleDirectory",
+      }
+
+      lua_ls_apidoc_ignored_modules = [
+         "moduleName.submoduleName"
+      ]
+
+   will generate API for module ``moduleName``, but will not include
+   ``moduleName.submoduleName``.
 
 Example output
 --------------

{sphinx_lua_ls-1.0.0 → sphinx_lua_ls-2.0.0}/pyproject.toml

@@ -47,7 +47,7 @@ test = [
 ]
 doc = [
     "sybil~=6.1",
-    "pydata-sphinx-theme>=0.15",
+    "furo>=2024",
     "sphinx_design>=0.6"
 ]
 
@@ -55,9 +55,10 @@ doc = [
 Documentation = "https://taminomara.github.io/sphinx-lua-ls/"
 Issues = "https://github.com/taminomara/sphinx-lua-ls/issues"
 Source = "https://github.com/taminomara/sphinx-lua-ls/"
+Changelog = "https://github.com/taminomara/sphinx-lua-ls/blob/main/CHANGELOG.md"
 
 [build-system]
-requires = ["setuptools>=45", "setuptools_scm[toml]>=6.2", "wheel>=0.40"]
+requires = ["setuptools>=60", "setuptools_scm[toml]>=8", "wheel>=0.40"]
 
 [tool.setuptools_scm]
 write_to = "sphinx_lua_ls/_version.py"