sphinx-lua-ls 2.0.1__tar.gz → 3.0.0__tar.gz

{sphinx_lua_ls-2.0.1 → sphinx_lua_ls-3.0.0}/.github/workflows/ci.yaml

@@ -32,11 +32,17 @@ jobs:
       - name: Install dependencies
         run: python -m pip install '.'
       - name: Download LuaLs for Linux
-        run: python sphinx_lua_ls/lua_ls.py linux x86_64 ~/lua_ls_release/ubuntu-latest
+        run: python sphinx_lua_ls/lua_ls.py linux x86_64 --runtime luals ~/lua_ls_release/ubuntu-latest
       - name: Download LuaLs for Windows
-        run: python sphinx_lua_ls/lua_ls.py win32 amd64 ~/lua_ls_release/windows-latest
+        run: python sphinx_lua_ls/lua_ls.py win32 amd64 --runtime luals ~/lua_ls_release/windows-latest
       - name: Download LuaLs for MacOs
-        run: python sphinx_lua_ls/lua_ls.py darwin x86_64 ~/lua_ls_release/macos-latest
+        run: python sphinx_lua_ls/lua_ls.py darwin arm --runtime luals ~/lua_ls_release/macos-latest
+      - name: Download EmmyLua for Linux
+        run: python sphinx_lua_ls/lua_ls.py linux x86_64 --runtime emmylua ~/lua_ls_release/ubuntu-latest
+      - name: Download EmmyLua for Windows
+        run: python sphinx_lua_ls/lua_ls.py win32 amd64 --runtime emmylua ~/lua_ls_release/windows-latest
+      - name: Download EmmyLua for MacOs
+        run: python sphinx_lua_ls/lua_ls.py darwin arm --runtime emmylua ~/lua_ls_release/macos-latest
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:

sphinx_lua_ls-3.0.0/CHANGELOG.md

@@ -0,0 +1,135 @@
+# Changelog
+
+## v3.0.0
+
+- **Breaking change:** changed how `apidoc` generates file names to avoid collisions.
+
+- Supported [EmmyLua] as an alternative backend for documentation export.
+
+  EmmyLua was recently re-implemented in Rust, and its new language server
+  provides some substantial benefits:
+
+  - it has stronger and more flexible type system,
+  - it handles aliases and enums way better than LuaLs,
+  - it supports namespaces,
+  - it exports way more metadata, including function overloads and class constructors,
+  - you don't have to annotate modules with `@class` and `!doctype` anymore.
+
+  I plan to use EmmyLua as the default language server since *v3.0.0*.
+
+- Long object signatures are now broken into multiple lines.
+
+- Supported using arbitrary types as object names, i.e.:
+
+  ```rst
+  .. lua:data:: [integer]: string
+  ```
+
+- Added `:globals:` flag for the `lua:autoobject` directive. It will allow
+  automatically documenting global variables defined in a module.
+
+- The `lua:autoindex` directive now lists globals defined in a module.
+
+- Added support for documenting class constructors:
+
+  ```rst
+  .. lua:class:: Foo(a, b, ...)
+  ```
+
+- Added directive for enums.
+
+- Supported generic parameters for functions, classes, aliases and enums:
+
+  ```rst
+  .. lua:class:: Foo<T>
+  ```
+
+- Improved linking to Lua language documentation to take into account
+  whether an item is supported for the given Lua version.
+
+- Added the `lua:lua` role to compensate for MySt not supporting default roles.
+
+  If Lua is your primary domain cross-referencing from markdown can be done like this:
+
+  ```md
+  Reference to a {lua}`logging.Logger.info`.
+  ```
+
+- Added the `lua:other-inherited-members` directive and `:inherited-members-table:`
+  flag for the `lua:autoobject` directive.
+
+  These allow listing all members that were inherited by a class but weren't
+  documented within the class body (see [#3]).
+
+- Supported markdown output for `apidoc`.
+
+- Added option to separate module members into their own files for `apidoc`.
+
+[EmmyLua]: https://github.com/EmmyLuaLs/emmylua-analyzer-rust/
+[#3]: https://github.com/taminomara/sphinx-lua-ls/issues/3
+
+**Migrating to 3.0.0:**
+
+- If you're using `apidoc`, you'll need to update links to your documentation.
+
+- You'll need to explicitly specify which language server to use
+  by including `lua_ls_backend` to your `conf.py`.
+
+## v2.0.1
+
+- Fixed documentation not being rebuilt after changing lua source code.
+
+## 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-2.0.1 → sphinx_lua_ls-3.0.0}/CONTRIBUTING.md

@@ -22,6 +22,10 @@
    pre-commit install
    ```
 
+5. If you're not on linux, install [EmmyLua Doc Cli].
+
+[EmmyLua Doc Cli]: https://github.com/EmmyLuaLs/emmylua-analyzer-rust/?tab=readme-ov-file#-installation
+
 ## Run tests
 
 To run tests, simply run `pytest` and `pyright`:
@@ -37,6 +41,12 @@ To fix code style, you can manually run pre-commit hooks:
 pre-commit run -a  # Fix code style.
 ```
 
+To regenerate data for regression tests, run
+
+```shell
+pytest --regen-all
+```
+
 
 ## Build docs
 

{sphinx_lua_ls-2.0.1/sphinx_lua_ls.egg-info → sphinx_lua_ls-3.0.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: sphinx-lua-ls
-Version: 2.0.1
-Summary: Automatic documentation generation via LuaLS
+Version: 3.0.0
+Summary: Automatic documentation generation via EmmyLua/LuaLs
 Author-email: Tamika Nomara <taminomara@gmail.com>
 License: MIT License
         
@@ -62,10 +62,12 @@ Requires-Dist: pytest~=7.4; extra == "test"
 Requires-Dist: sybil~=6.1; extra == "test"
 Requires-Dist: pytest-regressions~=2.7; extra == "test"
 Requires-Dist: beautifulsoup4~=4.13; extra == "test"
+Requires-Dist: myst-parser~=4.0; extra == "test"
 Provides-Extra: doc
 Requires-Dist: sybil~=6.1; extra == "doc"
 Requires-Dist: furo>=2024; extra == "doc"
 Requires-Dist: sphinx_design>=0.6; extra == "doc"
+Requires-Dist: myst-parser~=4.0; extra == "doc"
 Dynamic: license-file
 
 # Sphinx plugin for Lua and Lua Language Server

sphinx_lua_ls-3.0.0/docs/example/.emmyrc.json

@@ -0,0 +1,20 @@
+{
+  "diagnostics": {
+    "enables": ["unknown-doc-tag"]
+  },
+  "runtime": {
+    "version": "Lua5.4",
+    "requireLikeFunction": [],
+    "frameworkVersions": [],
+    "extensions": [],
+    "requirePattern": [],
+    "classDefaultCall": {
+      "functionName": "__init",
+      "forceNonColon": true,
+      "forceReturnSelf": true
+    }
+  },
+  "doc": {
+    "knownTags": ["doctype", "doc"]
+  }
+}

{sphinx_lua_ls-2.0.1 → sphinx_lua_ls-3.0.0}/docs/example/logging.lua

@@ -1,53 +1,38 @@
+--- @namespace logging
+
 --- A generic logging module, just to demonstrate you documentation.
----
---- .. lua:autoobject:: LOG_LEVEL
----    :global:
----
---- !doctype module
---- @class logging
-logging = {}
+local logging = {}
 
 --- Represents message severity.
 ---
---- @alias logging.Level integer
-logging.Level = {}
+--- @enum Level
+logging.Level = {
+    --- For debug messages, hidden by default.
+    Debug = 1,
 
---- For debug messages, hidden by default.
----
---- @type logging.Level
-logging.Level.Debug = 1
+    --- For info messages.
+    Info = 2,
 
---- For info messages.
----
---- @type logging.Level
-logging.Level.Info = 2
+    --- For warnings, when behavior may be different from what users expect.
+    Warning = 3,
 
---- For warnings, when behavior may be different from what users expect.
----
---- @type logging.Level
-logging.Level.Warning = 3
-
---- For errors, when the system stops working.
----
---- @type logging.Level
-logging.Level.Error = 4
+    --- For errors, when the system stops working.
+    Error = 4,
+}
 
 --- Default log level.
 ---
---- @type logging.Level
+--- @type Level
 LOG_LEVEL = LOG_LEVEL or logging.Level.Info
 
 --- An object for logging messages.
 ---
---- @class logging.Logger
+--- @class Logger
 logging.Logger = {}
 
---- Create a new logger.
----
 --- @param name string name of the logger, will be added to every message.
 --- @param level logging.Level? level of the logger, equals to `LOG_LEVEL` by default.
---- @return logging.Logger
-function logging.Logger.new(name, level) return {} end
+function logging.Logger.__init(name, level) end
 
 --- Print a debug message.
 ---

sphinx_lua_ls-3.0.0/docs/source/apidoc.rst

@@ -0,0 +1,79 @@
+Generating API references
+=========================
+
+: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`` or ``.md`` files.
+Fortunately, Sphinx-LuaLs 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`` or ``.md`` files should be placed.
+
+For example, to generate API reference for module ``moduleName``
+in directory ``moduleDirectory``, add the following:
+
+.. tab-set::
+   :sync-group: lang
+
+   .. tab-item:: RST
+      :sync: rst
+
+      .. code-block:: python
+
+         lua_ls_apidoc_roots = {
+            "moduleName": "moduleDirectory",
+         }
+
+   .. tab-item:: Markdown
+      :sync: md
+
+      .. code-block:: python
+
+         lua_ls_apidoc_format = "md"
+         lua_ls_apidoc_roots = {
+            "moduleName": "moduleDirectory",
+         }
+
+Upon start, Sphinx-LuaLs will recursively create ``.rst`` or ``.md`` files
+in ``moduleDirectory``. ``moduleDirectory/index`` will contain reference for
+``moduleName``. Then, for every submodule of ``moduleName``, there will be another
+``.rst`` or ``.md`` 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`` into a table of contents
+in your main ``index.rst``/``index.md``.
+
+Settings
+--------
+
+You can override default settings using :py:data:`lua_ls_apidoc_max_depth`,
+:py:data:`lua_ls_apidoc_default_options`,
+:py:data:`lua_ls_apidoc_ignored_modules`,
+:py:data:`lua_ls_apidoc_separate_members`,
+and :py:data:`lua_ls_apidoc_format`;
+see `settings <settings.html>`_ for more info.
+
+For example, here's how to enable documentation for members without description,
+protected members, and global variables:
+
+.. code-block:: python
+
+   lua_ls_apidoc_default_options = {
+      # Document members without description.
+      "undoc-members": "",
+      # Document protected members.
+      "protected-members": "",
+      # Document module's global variables.
+      "globals": "",
+      # Override default ordering.
+      "member-order": "alphabetical",
+      "module-member-order": "groupwise",
+      # Add table with inherited members for classes.
+      "inherited-members-table": "",
+   }