Merge pull request #1128 from sphinx-contrib/deprecate-page-specific-editor-overrides

flag page-specific editor overrides as deprecated

Author: jdknight

doc/_themes/sphinx13b/static/sphinx13b.css

@@ -438,6 +438,10 @@ div.viewcode-block:target {
     border-bottom: 1px solid #ac9;
 }
 
+span.deprecated {
+    font-weight: bold;
+}
+
 .contentstable {
     margin-left: 30px;
     margin: 0 auto;

doc/directives.rst

@@ -214,6 +214,11 @@ Common
     .. rst:directive:option:: editor: value
         :type: v1, v2
 
+        .. deprecated:: 2.14
+
+            Support for page-specific editor overrides will be removed in 2026
+            as Confluence Cloud removes support for the ``v1`` editor.
+
         Pages are publish with the editor type configured through the
         :lref:`confluence_editor` option. However, users can override the
         editor for a specific page using the ``editor`` metadata option.

sphinxcontrib/confluencebuilder/builder.py

@@ -954,6 +954,15 @@ def _extract_metadata(self, docname, doctree):
                 else:
                     metadata[k] = v
 
+                if k == 'editor':
+                    msg = 'page-specific editor overrides are deprecated'
+                    if node.source:
+                        lpf = f'#{node.line}' if node.line else ''
+                        self.warn(f'{msg}: {node.source}{lpf}',
+                            subtype='deprecated')
+                    else:
+                        self.warn(f'{msg}: {docname}', subtype='deprecated')
+
             node.parent.remove(node)
 
     def _find_title_element(self, doctree):

tests/unit-tests/datasets/metadata-legacy/index.rst

@@ -0,0 +1,5 @@
+confluence metadata
+-------------------
+
+.. confluence_metadata::
+    :editor: v2

tests/unit-tests/datasets/metadata/index.rst

@@ -2,6 +2,5 @@ confluence metadata
 -------------------
 
 .. confluence_metadata::
-    :editor: v2
     :full-width: true
     :labels: tag-a tag-c

tests/unit-tests/test_confluence_metadata.py

@@ -23,11 +23,6 @@ def test_confluence_metadata_directive_expected(self):
             doc_metadata = builder_metadata['index']
             self.assertTrue(doc_metadata)
 
-            # verify expected editor override
-            self.assertTrue('editor' in doc_metadata)
-            editor = doc_metadata['editor']
-            self.assertEqual(editor, 'v2')
-
             # verify expected full-width override
             self.assertTrue('fullWidth' in doc_metadata)
             editor = doc_metadata['fullWidth']
@@ -40,6 +35,23 @@ def test_confluence_metadata_directive_expected(self):
             self.assertIn('tag-a', labels)
             self.assertIn('tag-c', labels)
 
+    def test_confluence_metadata_directive_legacy(self):
+        dataset = self.datasets / 'metadata-legacy'
+        with self.prepare(dataset, relax=True) as app:
+            app.build()
+            builder_metadata = app.builder.metadata
+
+            self.assertTrue(builder_metadata)
+            self.assertTrue('index' in builder_metadata)
+
+            doc_metadata = builder_metadata['index']
+            self.assertTrue(doc_metadata)
+
+            # verify expected editor override
+            self.assertTrue('editor' in doc_metadata)
+            editor = doc_metadata['editor']
+            self.assertEqual(editor, 'v2')
+
     @setup_builder('html')
     def test_html_confluence_metadata_directive_ignore(self):
         with self.prepare(self.dataset, relax=True) as app:

tests/unit-tests/test_local_toc.py

@@ -15,7 +15,7 @@ def setUpClass(cls):
 
     @setup_builder('confluence')
     def test_storage_local_toc(self):
-        out_dir = self.build(self.dataset)
+        out_dir = self.build(self.dataset, relax=True)
 
         with parse('rst-v1', out_dir) as data:
             # for v1, no a-tags

tests/unit-tests/test_references_confluence.py

@@ -32,7 +32,7 @@ def setUpClass(cls):
 
     @setup_builder('confluence')
     def test_storage_references_confluence(self):
-        out_dir = self.build(self.dataset)
+        out_dir = self.build(self.dataset, relax=True)
 
         # expected page names
         rst_v1_first_name = 'reStructuredText v1 First'