Merge pull request #960 from sphinx-contrib/migrate-away-from-select-…

…transforms

Rework literal block language overrides

doc/configuration.rst

@@ -1882,24 +1882,27 @@ Advanced processing configuration
     - :ref:`Jira directives <jira-directives>`
     - :ref:`Jira roles <jira-roles>`
 
-.. confval:: confluence_lang_transform
+.. |confluence_lang_overrides| replace:: ``confluence_lang_overrides``
+.. _confluence_lang_overrides:
+
+.. confval:: confluence_lang_overrides
 
-    .. versionchanged:: 2.1 Support a ``None`` return to use a default value.
+    .. versionadded:: 2.6
 
-    A function to override the translation of literal block-based directive
-    language values to Confluence supported code block macro language values.
-    The default translation accepts `Pygments documented language types`_ to
+    A dictionary to override literal block-based directive language values to
+    a Confluence supported code block macro language values. The default
+    mapping accepts `Pygments documented language types`_ to
     `Confluence-supported syntax highlight languages`_.
 
     .. code-block:: python
 
-       def my_language_translation(lang):
-           return 'default'
-
-       confluence_lang_transform = my_language_translation
+        confluence_lang_overrides = {
+            'rs': 'rust',
+            'rust': 'rust',
+        }
 
-    In the event that the transform returns a ``None`` value, the provided
-    language type will be transform to a default language type for a language
+    In the event that a language entry is missing or returns a ``None`` value,
+    the provided language type will be transform to a default language type
     as if this transform was not provided.
 
 .. |confluence_latex_macro| replace:: ``confluence_latex_macro``
@@ -2095,11 +2098,18 @@ Other options
     warning types that may be suppressed:
 
     - ``confluence`` -- All warnings
+    - ``confluence.deprecated`` -- Configuration deprecated warnings
     - ``confluence.unsupported_code_lang`` -- Unsupported code language
 
 Deprecated options
 ------------------
 
+.. confval:: confluence_lang_transform
+
+    .. versionchanged:: 2.6
+
+    This option has been replaced by |confluence_lang_overrides|_.
+
 .. confval:: confluence_master_homepage
 
     .. versionchanged:: 1.6

sphinxcontrib/confluencebuilder/__init__.py

@@ -220,7 +220,7 @@ def setup(app):
     # Configuration for named JIRA Servers
     cm.add_conf('confluence_jira_servers', 'confluence')
     # Translation of a raw language to code block macro language.
-    cm.add_conf('confluence_lang_transform', 'confluence')
+    cm.add_conf('confluence_lang_overrides', 'confluence')
     # Macro configuration for Confluence-managed LaTeX content.
     cm.add_conf('confluence_latex_macro', 'confluence')
     # Link suffix for generated files.
@@ -265,6 +265,8 @@ def setup(app):
     cm.add_conf_bool('confluence_adv_aggressive_search')
     # replaced by confluence_permit_raw_html
     cm.add_conf_bool('confluence_adv_permit_raw_html')
+    # replaced by confluence_lang_overrides
+    cm.add_conf('confluence_lang_transform', 'confluence')
     # replaced by confluence_root_homepage
     cm.add_conf('confluence_master_homepage')
     # confluence_parent_page supports both names and identifiers

sphinxcontrib/confluencebuilder/builder.py

@@ -183,8 +183,14 @@ def link_transform(docname):
         else:
             self.link_transform = link_transform
 
-        if self.config.confluence_lang_transform is not None:
-            self.lang_transform = self.config.confluence_lang_transform
+        if self.config.confluence_lang_overrides is not None:
+            if isinstance(self.config.confluence_lang_overrides, dict):
+                def lang_transform(lang):
+                    return self.config.confluence_lang_overrides.get(lang)
+
+                self.lang_transform = lang_transform
+            else:
+                self.lang_transform = self.config.confluence_lang_overrides
         else:
             self.lang_transform = None
 

sphinxcontrib/confluencebuilder/config/checks.py

@@ -356,9 +356,11 @@ def validate_configuration(builder):
 
     # ##################################################################
 
-    # confluence_lang_transform
-    validator.conf('confluence_lang_transform') \
-             .callable_()
+    # confluence_lang_overrides
+    try:
+        validator.conf('confluence_lang_overrides').dict_str_str()
+    except ConfluenceConfigError:
+        validator.conf('confluence_lang_overrides').callable_()
 
     # ##################################################################
 

sphinxcontrib/confluencebuilder/config/defaults.py

@@ -77,6 +77,10 @@ def apply_defaults(builder):
     if conf.confluence_jira_servers is None:
         conf.confluence_jira_servers = {}
 
+    if conf.confluence_lang_overrides is None and \
+            conf.confluence_lang_transform is not None:
+        conf.confluence_lang_overrides = conf.confluence_lang_transform
+
     if conf.confluence_latex_macro and \
             not isinstance(conf.confluence_latex_macro, dict):
         conf.confluence_latex_macro = {

sphinxcontrib/confluencebuilder/config/notifications.py

@@ -12,6 +12,8 @@
         'use "confluence_cleanup_search_mode" instead',
     'confluence_adv_permit_raw_html':
         'use "confluence_permit_raw_html" instead',
+    'confluence_lang_transform':
+        'use "confluence_lang_overrides" instead',
     'confluence_adv_trace_data':
         'to be removed in a future version',
     'confluence_adv_writer_no_section_cap':
@@ -52,7 +54,7 @@ def deprecated(validator):
     # inform users of a deprecated configuration being used
     for key, msg in DEPRECATED_CONFIGS.items():
         if config[key] is not None:
-            logger.warn(f'{key} deprecated; {msg}')
+            logger.warn(f'{key} deprecated; {msg}', subtype='deprecated')
 
 
 def warnings(validator):

tests/unit-tests/test_config_checks.py

@@ -485,13 +485,18 @@ def test_config_check_jira_servers(self):
             self._try_config()
 
     def test_config_check_lang_transform(self):
+        self.config['confluence_lang_overrides'] = {
+            'key': 'value',
+        }
+        self._try_config()
+
         def mock_transform(lang):
             return 'default'
 
-        self.config['confluence_lang_transform'] = mock_transform
+        self.config['confluence_lang_overrides'] = mock_transform
         self._try_config()
 
-        self.config['confluence_lang_transform'] = 'invalid'
+        self.config['confluence_lang_overrides'] = 'invalid'
         with self.assertRaises(ConfluenceConfigError):
             self._try_config()
 

tests/unit-tests/test_sphinx_codeblock_highlight.py

@@ -106,15 +106,44 @@ def test_storage_sphinx_codeblock_highlight_none(self):
             self._verify_set_languages(languages, expected)
 
     @setup_builder('confluence')
-    def test_storage_sphinx_codeblock_highlight_override(self):
+    def test_storage_sphinx_codeblock_highlight_override_default(self):
         config = dict(self.config)
 
+        config['confluence_lang_overrides'] = {
+            'csharp': 'custom-csharp',
+        }
+
+        out_dir = self.build(self.dataset, config=config,
+            filenames=['code-block-highlight'])
+
+        with parse('code-block-highlight', out_dir) as data:
+            expected = [
+                'python',
+                'bash',
+                'custom-csharp',
+                'python',
+                'html/xml',
+                'python',
+            ]
+
+            languages = data.find_all('ac:parameter', {'ac:name': 'language'})
+            self._verify_set_languages(languages, expected)
+
+    @setup_builder('confluence')
+    def test_storage_sphinx_codeblock_highlight_override_legacy(self):
+        config = dict(self.config)
+
+        # ignore warnings in sphinx v7.3+ about non-cachable configuration
+        config['suppress_warnings'] = [
+            'config.cache',
+        ]
+
         def test_override_lang_method(lang):
             if lang == 'csharp':
                 return 'custom-csharp'
 
             return None
-        config['confluence_lang_transform'] = test_override_lang_method
+        config['confluence_lang_overrides'] = test_override_lang_method
 
         out_dir = self.build(self.dataset, config=config,
             filenames=['code-block-highlight'])