Merge pull request #833 from sphinx-contrib/provide-cdata-quirk

cdata workaround for confluence 8.0.x to 8.2.x

Author: jdknight

CHANGES.rst

@@ -6,6 +6,7 @@ Development
 * Fixed re-publishing issues when certain options change (e.g. parent page)
 * Improve support when using the sphinxcontrib-video extension
 * Introduce the ``confluence_permit_raw_html`` option
+* Provide quirk for CDATA issues on Confluence 8.0.x to 8.2.x
 * Support configuring the theme on generated code block macros
 * Support page-specific editor and full-width overrides
 * Support page-specific parent identifier overrides when publishing

sphinxcontrib/confluencebuilder/__init__.py

@@ -245,6 +245,8 @@ def setup(app):
     cm.add_conf('confluence_adv_node_handler')
     # Permit any string value to be provided as the editor.
     cm.add_conf('confluence_adv_permit_editor', 'confluence')
+    # Flag to tweak code-block CDATA EOFs to prevent publishing issues.
+    cm.add_conf_bool('confluence_adv_quirk_cdata')
     # List of optional features/macros/etc. restricted for use.
     cm.add_conf('confluence_adv_restricted', 'confluence')
     # Enablement of tracing processed data.

sphinxcontrib/confluencebuilder/exceptions.py

@@ -263,6 +263,35 @@ def __init__(self, server_url):
 '''.format(url=server_url))
 
 
+class ConfluenceUnexpectedCdataError(ConfluenceError):
+    def __init__(self):
+        super().__init__('''
+---
+Unexpected Confluence XML stream CDATA parsing error
+
+Confluence has reported an error processing a document which contains
+CDATA data (e.g. a code block using `<![CDATA[data]]>`). This is
+unexpected since the data should be properly formed. There is a high
+chance that this is occurring on a Confluence instance which introduced
+some processing logic that incorrectly breaks the parsing of CDATA EOF
+strings (as of Confluence 8.x). This should be addressed in Confluence
+8.3.0 (or newer) release [1].
+
+To workaround this issue for the configured Confluence instance, a user
+can enable the `confluence_adv_quirk_cdata` inside their `conf.py`
+configuration file. For example:
+
+    confluence_adv_quirk_cdata = True
+
+If enabling this option does not resolve the publication issue, then
+this error message does not apply. Feel free to report this issue noting
+the exception message above this message.
+
+[1]: https://jira.atlassian.com/browse/CONFSERVER-82849
+---
+''')
+
+
 class ConfluenceUnreconciledPageError(ConfluenceError):
     def __init__(self, page_name, page_id, url, ex):
         super().__init__('''

sphinxcontrib/confluencebuilder/publisher.py

@@ -16,6 +16,7 @@
 from sphinxcontrib.confluencebuilder.exceptions import ConfluencePermissionError
 from sphinxcontrib.confluencebuilder.exceptions import ConfluencePublishAncestorError
 from sphinxcontrib.confluencebuilder.exceptions import ConfluencePublishSelfAncestorError
+from sphinxcontrib.confluencebuilder.exceptions import ConfluenceUnexpectedCdataError
 from sphinxcontrib.confluencebuilder.exceptions import ConfluenceUnreconciledPageError
 from sphinxcontrib.confluencebuilder.logger import ConfluenceLogger as logger
 from sphinxcontrib.confluencebuilder.rest import Rest
@@ -922,6 +923,9 @@ def store_page(self, page_name, data, parent_id=None):
                         self.rest_client.post(url, labels)
 
                 except ConfluenceBadApiError as ex:
+                    if str(ex).find('CDATA block has embedded') != -1:
+                        raise ConfluenceUnexpectedCdataError from ex
+
                     # Check if Confluence reports that the new page request
                     # fails, indicating it already exists. This is usually
                     # (outside of possible permission use cases) that the page
@@ -1235,6 +1239,8 @@ def _update_page(self, page, page_name, data, parent_id=None):
         try:
             self.rest_client.put('content', page_id_explicit, update_page)
         except ConfluenceBadApiError as ex:
+            if str(ex).find('CDATA block has embedded') != -1:
+                raise ConfluenceUnexpectedCdataError from ex
 
             # Handle select API failures by waiting a moment and retrying the
             # content request. If it happens again, the put request will fail as

sphinxcontrib/confluencebuilder/storage/translator.py

@@ -3613,5 +3613,19 @@ def _escape_cdata(self, data):
         Returns:
             the escaped text
         """
-        data = data.replace(']]>', ']]]]><![CDATA[>')
+
+        # workaround for Confluence 8.0.x to 8.2.x series
+        # (https://jira.atlassian.com/browse/CONFSERVER-82849)
+        #
+        # The else case here should be always working; however, in some
+        # Confluence instances, there was a window where pages could not
+        # be uploaded since Confluence would refuse the EOF sequence for
+        # CDATA blocks. This workaround can help a user get their content
+        # published at the unfortunate tweak of changing any trailing EOF
+        # CDATA blocks to have a space character included.
+        if self.builder.config.confluence_adv_quirk_cdata:
+            data = data.replace(']]>', ']] >')
+        else:
+            data = data.replace(']]>', ']]]]><![CDATA[>')
+
         return ConfluenceBaseTranslator.encode(self, data)