Merge pull request #1099 from sphinx-contrib/limited-inline-comment-check

initial/limited inlined comment check support

Author: jdknight

doc/configuration.rst

@@ -1795,6 +1795,29 @@ Advanced publishing configuration
 
     .. versionadded:: 2.10
 
+.. confval:: confluence_publish_skip_commented_pages
+
+    .. note::
+
+        There is no support to keep inlined comments on updated pages at
+        this time.
+
+    Indicates to skip updates on pages which have inlined comments. Before
+    a page update is issued, a warning will be generated if this extension
+    detects that a page has inlined comments added to it. Page updates
+    remove any inlined comments embedded in the page source. If a users
+    wants to prevent any updates on pages to prevent the loss of inlined
+    comments, they can configure this option to ``True``. By default, pages
+    will always be updated with a value of ``False``.
+
+    .. code-block:: python
+
+        confluence_publish_skip_commented_pages = True
+
+    See also :lref:`suppress_warnings_config`.
+
+    .. versionadded:: 2.13
+
 .. confval:: confluence_request_session_override
 
     A hook to manipulate a Requests_ session prepared by this extension. Allows
@@ -2294,6 +2317,8 @@ Third-party related options
 Other options
 -------------
 
+.. _suppress_warnings_config:
+
 .. confval:: suppress_warnings
 
     This extension supports suppressing warnings using Sphinx's
@@ -2303,8 +2328,17 @@ Other options
     - ``confluence`` -- All warnings
     - ``confluence.deprecated`` -- Configuration deprecated warnings
     - ``confluence.deprecated_develop`` -- Development deprecated warnings
+    - ``confluence.inline-comment`` -- Inlined comment warnings
     - ``confluence.unsupported_code_lang`` -- Unsupported code language
 
+    For example:
+
+    .. code-block:: python
+
+        suppress_warnings = [
+            'confluence.unsupported_code_lang',
+        ]
+
     .. versionadded:: 2.1
 
 Deprecated options

sphinxcontrib/confluencebuilder/__init__.py

@@ -218,6 +218,8 @@ def setup(app):
     cm.add_conf('confluence_publish_retry_attempts')
     # Duration (in seconds) between retrying failed API requests
     cm.add_conf('confluence_publish_retry_duration')
+    # Whether to skip page updates for pages that have inlined comments
+    cm.add_conf_bool('confluence_publish_skip_commented_pages')
     # Manipulate a requests instance.
     cm.add_conf('confluence_request_session_override')
     # Authentication passthrough for Confluence REST interaction.

sphinxcontrib/confluencebuilder/publisher.py

@@ -1041,6 +1041,13 @@ def store_page(self, page_name, data, parent_id=None):
                 logger.verbose(f'no changes in page: {page_name}')
                 return page['id']
 
+        # check for inlined comments
+        if page:
+            icdrop = self._manage_inlined_comments(page, page_name, data)
+            if icdrop and self.config.confluence_publish_skip_commented_pages:
+                logger.verbose(f'skipping publish due to comments: {page_name}')
+                return page['id']
+
         try:
             # new page
             if not page:
@@ -1222,6 +1229,13 @@ def store_page_by_id(self, page_name, page_id, data):
                 logger.verbose(f'no changes in page: {page_name}')
                 return page_id
 
+        # check for inlined comments
+        if page:
+            icdrop = self._manage_inlined_comments(page, page_name, data)
+            if icdrop and self.config.confluence_publish_skip_commented_pages:
+                logger.verbose(f'skipping publish due to comments: {page_name}')
+                return page_id
+
         try:
             self._update_page(page, page_name, data)
         except ConfluencePermissionError as ex:
@@ -1498,6 +1512,40 @@ def _build_page(self, page_name, data):
 
         return page
 
+    def _manage_inlined_comments(self, page, page_name, data):
+        """
+        manage inlined comments for a page update
+
+        This call will attempt to manage a page update event where the
+        original page (``page``) may include inlined comments that are not
+        included in the proposed page update (``data``).
+
+        Args:
+            page: the page data from confluence to update
+            page_name: the page title to use on the update page
+            data: the new page data to be applied
+
+        Returns:
+            whether at least one inlined comment will be dropped
+        """
+
+        try:
+            existing_data = page['body']['storage']['value']
+        except KeyError:
+            return False
+
+        # At this time, we only have this crude check for inlined comments.
+        # We check if the original page has any inlined comment markers. If
+        # so, we generate a warning. A publish even will still go through,
+        # but it generates a warning to inform users and allows a publish
+        # even to stop if `--fail-on-warning` is set.
+        if '<ac:inline-comment-marker' in existing_data:
+            logger.warn(f'inline comment detected (page "{page_name}")',
+                subtype='inline-comment')
+            return True
+
+        return False
+
     def _next_page_fields(self, rsp, fields, offset):
         """
         extract next query fields from a response