fix: avoid warnings in custom config option extension (#1014)

* Clear option index for document on rebuild.

Implement the clear_doc() method to fix warnings about duplicate
object definitions when using incremental builds.  The data attribute
is cached in the build environment, thus the duplication warning
triggers on each reprocessed document.  But clear_doc() is called for
each document being re-read, so it should simply remove the matching
previous entries.

Not important for sections, these amy simply linger after a partial
rebuild if removed.  No biggie.

* Fix initialization type of initial sections data.

As declared, the default value should be a set, while the initial_data
template contained an empty list.

* Implement merge_domaindata() method for safe parallel builds.

Sphinx may process different documents concurrently in several
runners.  The resulting domain data (signatures and corresponding
object entries) must be merged by the Domain code.

Declare this extension safe for parallel processing with the method
now implemented.

* Modernize for Python >= 3.9, fix linter warnings.

Signed-off-by: André Colomb <src@andre.colomb.de>

Author: acolomb

_ext/syncthing_config.py

@@ -4,19 +4,20 @@
 Modeled after the standard :directive:`cmdoption` directive.
 """
 
-from typing import Tuple, Dict, Iterator, Set, NamedTuple
+from typing import Any, Iterator, NamedTuple, Tuple
 
 from docutils.nodes import Element
 from docutils.parsers.rst import directives
+
 from sphinx import addnodes
 from sphinx.addnodes import pending_xref
 from sphinx.builders import Builder
 from sphinx.directives import ObjectDescription
 from sphinx.domains import Domain, ObjType
 from sphinx.environment import BuildEnvironment
 from sphinx.roles import XRefRole
-from sphinx.util.nodes import make_refnode
 from sphinx.util import logging
+from sphinx.util.nodes import make_refnode
 
 
 __licence__ = 'BSD (3 clause)'
@@ -116,11 +117,11 @@ class SyncthingConfigDomain(Domain):
     }
 
     @property
-    def config_sections(self) -> Set[str]:
-        return self.data.setdefault('sections', [])
+    def config_sections(self) -> set[str]:
+        return self.data.setdefault('sections', set())
 
     @property
-    def config_options(self) -> Dict[str, Tuple]:
+    def config_options(self) -> dict[str, Tuple]:
         return self.data.setdefault('options', {})  # fullname -> (docname, node_id)
 
     def get_full_qualified_name(self, node):  # FIXME: what is this for?!
@@ -168,11 +169,34 @@ def add_config_option(self, signature, section, option, anchor, location=None):
             docname=self.env.docname,
             anchor=anchor, priority=0)
 
+    def clear_doc(self, docname: str):
+        self.data['options'] = {
+            signature: entry
+            for signature, entry in self.config_options.items()
+            if entry.docname != docname
+        }
+
+    def merge_domaindata(self, docnames: set[str], otherdata: dict[str, Any]):
+        self.config_sections.update(otherdata.get('sections', set()))
+
+        for signature, entry in otherdata.get('options', {}).items():
+            if entry.docname in docnames:
+                if signature in self.config_options:
+                    other = self.config_options[signature]
+                    logger.warning(
+                        'Duplicate object description of %s, other instance in %s',
+                        entry.name, other.docname
+                    )
+                self.config_options[signature] = entry
+
 
 def setup(app):
     """Install the plugin.
 
     :param app: Sphinx application context.
     """
     app.add_domain(SyncthingConfigDomain)
-    return
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }