support deprecated api warnings when publishing

Updates the `confluence_publish_debug` option to now accept a new value
`deprecated`, which can be used by developers to help warn when using
API calls that Atlassian has marked as deprecated.

Signed-off-by: James Knight <james.d.knight@live.com>

sphinxcontrib/confluencebuilder/debug.py

@@ -18,9 +18,13 @@ class PublishDebug(Flag):
 
     # do not perform any logging
     none = auto()
+    # logs warnings when confluence reports a deprecated api call
+    deprecated = auto()
     # log raw requests/responses in stdout with header data
     headers = auto()
     # log urllib3-supported debug messages
     urllib3 = auto()
     # enable all logging
     all = headers | urllib3
+    # enable all developer logging
+    developer = deprecated | all

sphinxcontrib/confluencebuilder/rest.py

@@ -377,6 +377,13 @@ def _process_request(self, method, path, *args, **kwargs):
                                 math.ceil(delay)))
                     self._reported_large_delay = True
 
+        # check if Confluence reports a `Deprecation` header in the response;
+        # if so, log a message is we have the debug message enabled to help
+        # inform developers that this api call may required updating
+        if PublishDebug.deprecated in self.config.confluence_publish_debug:
+            if rsp.headers.get('Deprecation'):
+                logger.warn(f'(warning) deprecated api call made: {path}')
+
         if rsp.status_code == 401:
             raise ConfluenceAuthenticationFailedUrlError
         if rsp.status_code == 403: