sphinx-lua-ls 0.0.4__tar.gz → 1.1.0__tar.gz

sphinx_lua_ls-1.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 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-0.0.4/sphinx_lua_ls.egg-info → sphinx_lua_ls-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: sphinx-lua-ls
-Version: 0.0.4
+Version: 1.1.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

{sphinx_lua_ls-0.0.4 → sphinx_lua_ls-1.1.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
 ----------
 
@@ -447,36 +451,49 @@ Autodoc directive
    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, 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:
 
-   .. note::
+   .. code-block:: lua
 
-      Tables are exported as :rst:dir:`data` by default, meaning that their contents
-      are not documented.
+      --- This is a module. Notice that we've declared it as a class
+      --- inherited from :lua:obj:`table`.
+      ---
+      --- @class library: table
+      local library = {}
 
-      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:
+      --- 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 a module. Notice that we've declared it as a class
-         --- inherited from `table`.
-         ---
-         --- @class library: table
-         local library = {}
+      return library
 
-         --- Submodules should also be declared as classes.
-         ---
-         --- @class library.submodule: table
-         library.submodule = {}
+   .. 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.
+
+      Make sure you separate separate comment markers from documentation by a space.
+      Otherwise, autodoc will not be able to tell your comments apart from content
+      automatically generated by Lua Language Server:
+
+      .. 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 +504,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.
 
@@ -522,6 +539,8 @@ Autodoc directive
       they are skipped even if :rst:dir:`members` is passed.
 
    .. rst:directive:option:: private-members
+                             protected-members
+                             package-members
 
       Include non-public members to the object's description.
 
@@ -566,6 +585,39 @@ Autodoc directive
          for enums (``@enum``). If ordering by source, enums will be placed
          at the end of the documentation.
 
+
+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!"
+
+
 Settings
 --------
 

{sphinx_lua_ls-0.0.4 → sphinx_lua_ls-1.1.0}/pyproject.toml

@@ -55,6 +55,7 @@ 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"]

{sphinx_lua_ls-0.0.4 → sphinx_lua_ls-1.1.0}/sphinx_lua_ls/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.0.4'
-__version_tuple__ = version_tuple = (0, 0, 4)
+__version__ = version = '1.1.0'
+__version_tuple__ = version_tuple = (1, 1, 0)