Allow extending or disabling global settings

Author: taminomara

docs/source/autodoc.rst

@@ -293,19 +293,14 @@ Autodoc directive
       for all objects nested within the root. That is, object's members,
       their members, and so on.
 
-      If
-      :rst:dir:`lua:autoobject:members`,
-      :rst:dir:`lua:autoobject:globals`,
-      :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.
+      Options like ``no-index`` or :rst:dir:`lua:autoobject:member-order` are always
+      passed down to all members.
+
+      List options like :rst:dir:`lua:autoobject:members`
+      or :rst:dir:`lua:autoobject:globals`
+      are passed down if they're empty or start with ``+``
+      (see :py:data:`lua_ls_default_options` for info on ``+``
+      and overriding defaults).
 
    .. rst:directive:option:: member-order
 

docs/source/settings.rst

@@ -56,6 +56,25 @@ Settings
           # And so on...
       }
 
+   If using defaults for the ``:members:``, ``:exclude-members:``, and other
+   list options, setting the option on a directive will override the default.
+   Instead, to extend the default list with the per-directive option,
+   the list may be prepended with a plus sign (``+``), as follows:
+
+   .. code-block:: rst
+
+      .. lua:autoobject:: Noodle
+         :members: eat
+         :private-members: +_spicy, _garlickly
+
+   Also, the defaults can be disabled per-directive with the negated form,
+   ``:no-option:`` as an option of the directive:
+
+   .. code-block:: rst
+
+      .. lua:autoobject:: foo
+         :no-undoc-members:
+
 .. py:data:: class_default_function_name
    :type: str
 

sphinx_lua_ls/autodoc.py

@@ -201,14 +201,14 @@ class AutodocUtilsMixin(sphinx_lua_ls.domain.LuaContextManagerMixin):
     """
 
     option_spec: ClassVar[dict[str, Callable[[str], Any]]] = {  # type: ignore
-        "members": utils.parse_list_option,
-        "undoc-members": utils.parse_list_option,
-        "private-members": utils.parse_list_option,
-        "protected-members": utils.parse_list_option,
-        "package-members": utils.parse_list_option,
-        "special-members": utils.parse_list_option,
-        "inherited-members": utils.parse_list_option,
-        "exclude-members": utils.parse_list_option,
+        "members": utils.parse_list_option_or_true,
+        "undoc-members": utils.parse_list_option_or_true,
+        "private-members": utils.parse_list_option_or_true,
+        "protected-members": utils.parse_list_option_or_true,
+        "package-members": utils.parse_list_option_or_true,
+        "special-members": utils.parse_list_option_or_true,
+        "inherited-members": utils.parse_list_option_or_true,
+        "exclude-members": utils.parse_list_option_or_true,
         "title": directives.unchanged,
         "index-title": directives.unchanged,
         "recursive": directives.flag,
@@ -220,7 +220,7 @@ class AutodocUtilsMixin(sphinx_lua_ls.domain.LuaContextManagerMixin):
         "module-member-order": lambda x: directives.choice(
             x, ("alphabetical", "groupwise", "bysource")
         ),
-        "globals": utils.parse_list_option,
+        "globals": utils.parse_list_option_or_true,
         "class-doc-from": lambda x: directives.choice(
             x, ("class", "both", "ctor", "separate", "none")
         ),
@@ -232,8 +232,14 @@ class AutodocUtilsMixin(sphinx_lua_ls.domain.LuaContextManagerMixin):
         ),
         "require-function-name": directives.unchanged,
         "require-separator": directives.unchanged,
-        **sphinx_lua_ls.domain.LuaObject.option_spec,
     }
+    option_spec.update(
+        {
+            f"no-{key}": directives.flag
+            for key in sphinx_lua_ls.domain.GLOBAL_OPTIONS & set(option_spec)
+        }
+    )
+    option_spec.update(sphinx_lua_ls.domain.LuaObject.option_spec)
 
     def render(self, root: Object, name: str, top_level: bool = False):
         if root.kind is None:
@@ -383,25 +389,39 @@ def _create_directive(
         top_level: bool = False,
     ) -> SphinxDirective:
         if top_level:
-            options = self.options.copy()
+            options = self.orig_options.copy()
             options.pop("module", None)
         else:
             options = {}
             for key in [
                 "member-order",
+                "no-member-order",
                 "module-member-order",
+                "no-module-member-order",
                 "recursive",
+                "no-recursive",
                 "no-index",
+                "no-no-index",
+                "no-index-entry",
+                "no-no-index-entry",
+                "no-contents-entry",
+                "no-no-contents-entry",
                 "inherited-members-table",
+                "no-inherited-members-table",
                 "class-doc-from",
+                "no-class-doc-from",
                 "class-signature",
+                "no-class-signature",
                 "annotate-require",
+                "no-annotate-require",
                 "require-function-name",
+                "no-require-function-name",
                 "require-separator",
+                "no-require-separator",
             ]:
-                if key in self.options:
-                    options[key] = self.options[key]
-            if "recursive" in self.options:
+                if key in self.orig_options:
+                    options[key] = self.orig_options[key]
+            if "recursive" in self.orig_options:
                 for key in [
                     "members",
                     "globals",
@@ -411,9 +431,17 @@ def _create_directive(
                     "package-members",
                     "special-members",
                     "inherited-members",
+                    "using",
                 ]:
-                    if key in self.options and self.options[key] is True:
-                        options[key] = self.options[key]
+                    if key in self.orig_options:
+                        if self.orig_options[key] is True:
+                            options[key] = self.orig_options[key]
+                        elif (
+                            self.orig_options[key] and self.orig_options[key][0] == "+"
+                        ):
+                            options[key] = self.orig_options[key]
+                            if f"no-{key}" in self.orig_options:
+                                options[f"no-{key}"] = self.orig_options[f"no-{key}"]
 
         match root.visibility:
             case Visibility.Private:
@@ -939,9 +967,7 @@ class AutoObjectDirective(AutodocUtilsMixin):
     has_content = True
 
     def run(self):
-        for name, option in self.lua_domain.config.default_options.items():
-            if name not in self.options:
-                self.options[name] = option
+        self.prepare_options()
 
         name = self.arguments[0].strip()
 

sphinx_lua_ls/config.py

@@ -87,7 +87,11 @@ def _options(name: str, value) -> dict[str, _t.Any]:
     for key, option in value.items():
         parser = sphinx_lua_ls.autodoc.AutoObjectDirective.option_spec.get(key, None)
         if parser is None:
-            raise ConfigError(f"unknown option in {name}: {key}")
+            raise ConfigError(f"unknown option in {name}: :{key}:")
+        if key not in sphinx_lua_ls.domain.GLOBAL_OPTIONS:
+            raise ConfigError(
+                f"incorrect option in {name}: :{key}: can't be set from config"
+            )
         _type(f"{name}[{key!r}]", option, str)
         try:
             new_value[key] = parser(option)

sphinx_lua_ls/domain.py

@@ -261,6 +261,54 @@ def pop_context(self):
         else:
             self.env.ref_context.pop("lua:using", None)
 
+    def prepare_options(self):
+        self.orig_options = self.options.copy()
+        for name, option in self.lua_domain.config.default_options.items():
+            if f"no-{name}" in self.options:
+                continue
+            if name not in self.options:
+                self.options[name] = option
+            else:
+                given_option = self.options[name]
+                if (
+                    isinstance(given_option, list)
+                    and given_option
+                    and given_option[0] == "+"
+                ):
+                    if isinstance(option, list):
+                        self.options[name] = option + given_option[1:]
+                    else:
+                        self.options[name] = given_option[1:]
+
+
+GLOBAL_OPTIONS = {
+    "no-index",
+    "no-index-entry",
+    "no-contents-entry",
+    "using",
+    "members",
+    "undoc-members",
+    "private-members",
+    "protected-members",
+    "package-members",
+    "special-members",
+    "inherited-members",
+    "exclude-members",
+    "title",
+    "index-title",
+    "recursive",
+    "index-table",
+    "inherited-members-table",
+    "member-order",
+    "module-member-order",
+    "globals",
+    "class-doc-from",
+    "class-signature",
+    "annotate-require",
+    "require-function-name",
+    "require-separator",
+}
+
 
 class LuaObject(
     ObjectDescription[tuple[str, str, str, str]], LuaContextManagerMixin, Generic[T]
@@ -295,6 +343,9 @@ class LuaObject(
         "using": utils.parse_list_option,
         **ObjectDescription.option_spec,
     }
+    option_spec.update(
+        {f"no-{key}": directives.flag for key in GLOBAL_OPTIONS & set(option_spec)}
+    )
 
     doc_field_types = [
         LuaTypedField(
@@ -327,9 +378,7 @@ class LuaObject(
     collected_bases: list[str] | None = None
 
     def run(self) -> list[nodes.Node]:
-        for name, option in self.lua_domain.config.default_options.items():
-            if name not in self.options:
-                self.options[name] = option
+        self.prepare_options()
         return super().run()
 
     def parse_signature(self, sig: str) -> tuple[str, T]:
@@ -955,9 +1004,7 @@ class LuaModule(LuaContextManagerMixin):
     }
 
     def run(self) -> list[nodes.Node]:
-        for name, option in self.lua_domain.config.default_options.items():
-            if name not in self.options:
-                self.options[name] = option
+        self.prepare_options()
 
         if self.env.ref_context.get("lua:class", None):
             raise self.severe("lua:module only available on top level")

sphinx_lua_ls/utils.py

@@ -387,7 +387,22 @@ def parse_list_option(value: str):
     if not value:
         return True
     else:
-        return separate_sig(value)
+        value = value.strip()
+        if value.startswith("+"):
+            return ["+", *separate_sig(value.lstrip("+, "))]
+        else:
+            return separate_sig(value)
+
+
+def parse_list_option_or_true(value: str):
+    if not value:
+        return True
+    else:
+        value = value.strip()
+        if value.startswith("+"):
+            return ["+", *separate_sig(value.lstrip("+, "))]
+        else:
+            return separate_sig(value)
 
 
 _VCS_MARKERS = [".git", ".hg", ".svn"]

test/roots/test-autodoc-settings-override/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

test/roots/test-autodoc-settings-override/conf.py

@@ -0,0 +1,12 @@
+project = "Test"
+copyright = "test"
+author = "test"
+
+extensions = ["sphinx_lua_ls"]
+lua_ls_backend = "emmylua"
+lua_ls_project_root = "lua"
+lua_ls_default_options = {
+    "members": "",
+    "exclude-members": "bar",
+    "undoc-members": "",
+}

test/roots/test-autodoc-settings-override/index.rst

@@ -0,0 +1,10 @@
+Test autodoc
+============
+
+.. container:: regression
+
+   .. lua:autoobject:: autodoc
+
+   .. lua:autoobject:: autodoc
+      :exclude-members: +foo
+      :no-undoc-members:

test/roots/test-autodoc-settings-override/lua/autodoc.lua

@@ -0,0 +1,17 @@
+--- @namespace autodoc
+
+--- Description
+local autodoc = {}
+
+--- Description.
+function autodoc.foo() end
+
+--- Description.
+function autodoc.bar() end
+
+--- Description.
+function autodoc.baz() end
+
+function autodoc.undoc() end
+
+return autodoc