From 58e3e8214985696c329a1332acc8019b2c0f23f1 Mon Sep 17 00:00:00 2001 From: James Knight Date: Sat, 12 Oct 2024 00:18:05 -0400 Subject: [PATCH] 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]: https://github.com/sphinx-doc/sphinx/pull/12767 Signed-off-by: James Knight --- .../confluencebuilder/singlebuilder.py | 26 ++++++++++++++----- 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/sphinxcontrib/confluencebuilder/singlebuilder.py b/sphinxcontrib/confluencebuilder/singlebuilder.py index 96cce106..6d519a0a 100644 --- a/sphinxcontrib/confluencebuilder/singlebuilder.py +++ b/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)