singlebuilder: switch to using write_documents call

Sphinx's builder implementation has added a final hint on the `write`
call and introduced a `write_documents` as a more appropriate hook for
processing documents [1]. This commit updates `SingleConfluenceBuilder`
to no longer use `write`, except for supporting legacy versions of
Sphinx that this extension still supports.

[1]: sphinx-doc/sphinx#12767

Signed-off-by: James Knight <[email protected]>

Author: jdknight

sphinxcontrib/confluencebuilder/singlebuilder.py

@@ -3,6 +3,7 @@
 # Copyright 2007-2019 by the Sphinx team (sphinx-doc/sphinx#AUTHORS)
 
 from docutils import nodes
+from sphinx import version_info as sphinx_version_info
 from sphinx.util.console import darkgreen  # pylint: disable=no-name-in-module
 from sphinx.util.display import progress_message
 from sphinxcontrib.confluencebuilder.builder import ConfluenceBuilder
@@ -16,6 +17,20 @@ class SingleConfluenceBuilder(ConfluenceBuilder):
     name = 'singleconfluence'
     supported_linkcode = name
 
+    def __init__(self, app, env=None):
+        super().__init__(app, env)
+
+        # As of Sphinx v8.1, the builder's the `write` call has be finalized.
+        # Support has been added to use the new `write_documents` call. To
+        # handle older versions of Sphinx this extension supports, register
+        # a `write` hook override still.
+        if sphinx_version_info < (8, 1, 0):
+            def compat(self, *args, **kwargs):
+                self.write_documents(None)
+
+            # pylint: disable=E1111
+            self.write = compat.__get__(self, self.__class__)
+
     def assemble_doctree(self):
         root_doc = self.config.root_doc
         tree = self.env.get_doctree(root_doc)
@@ -64,12 +79,11 @@ def get_target_uri(self, docname, typ=None):
 
         return self.link_transform(docname)
 
-    def write(self, build_docnames, updated_docnames, method='update'):
-        docnames = self.env.all_docs
-        if self.config.root_doc not in docnames:
-            logger.error('singleconfluence requires root_doc')
-            return
+    def prepare_writing(self, docnames):
+        # override; nothing to prepare
+        pass
 
+    def write_documents(self, _docnames):
         root_doctitle = self._process_root_document()
         if not root_doctitle:
             logger.error('singleconfluence requires title on root_doc')
@@ -100,7 +114,7 @@ def write(self, build_docnames, updated_docnames, method='update'):
             # register title targets for references before assembling doc
             # re-works them into a single document
             title_db = {}
-            for docname in docnames:
+            for docname in self.env.all_docs:
                 doctree = self.env.get_doctree(docname)
                 self._register_doctree_targets(docname, doctree, title_db)