Support REST v2 API Calls

doc/configuration.rst

@@ -489,6 +489,26 @@ Generic configuration
 Publishing configuration
 ------------------------
 
+.. |confluence_api_mode| replace:: ``confluence_api_mode``
+.. _confluence_api_mode:
+
+.. confval:: confluence_api_mode
+
+    Configures the API mode to use for REST requests. Certain Confluence
+    instances support a newer version of REST APIs (e.g. Confluence Cloud).
+    This extension will attempt to use an appropriate API mode for a
+    configuration set. However, a user can override the operating API mode
+    based on preference or when handling situations where this extension
+    cannot automatically determine the best API mode to use. Values
+    accepted are either ``v1`` or ``v2``.
+
+    .. code-block:: python
+
+        confluence_api_mode = 'v2'
+
+    By default, if a Confluence Cloud configuration is detected, this
+    extension will use ``v2``. For all other cases, the default is ``v1``.
+
 .. |confluence_ask_password| replace:: ``confluence_ask_password``
 .. _confluence_ask_password:
 
@@ -1478,17 +1498,6 @@ Advanced publishing configuration
 
     See also |confluence_publish_allowlist|_.
 
-.. confval:: confluence_publish_disable_api_prefix
-
-    A boolean value which explicitly disables the use of the ``rest/api`` in
-    the Confluence publish URL. This can be useful for environments where the
-    API endpoint for a Confluence instance is proxied through a non-standard
-    location. By default, API prefixes are enabled with a value of ``False``.
-
-    .. code-block:: python
-
-        confluence_publish_disable_api_prefix = True
-
 .. |confluence_publish_dryrun| replace:: ``confluence_publish_dryrun``
 .. _confluence_publish_dryrun:
 
@@ -1622,6 +1631,40 @@ Advanced publishing configuration
 
     See also |confluence_publish_orphan|_.
 
+.. |confluence_publish_override_api_prefix| replace:: ``confluence_publish_override_api_prefix``
+.. _confluence_publish_override_api_prefix:
+
+.. confval:: confluence_publish_override_api_prefix
+
+    .. versionadded:: 2.5
+
+    Allows a user to override the path-prefix value used for API requests.
+    API paths are commonly prefixed, such as ``rest/api/`` for API v1 and
+    ``api/v2/`` for API v2. However, if a user is interacting with a Confluence
+    instance which system administrators have configured non-standard
+    locations for API endpoints, requests made by this extension will fail.
+
+    To support custom API endpoint paths, this option can be used to indicate
+    what prefix to use, if any. By default, this extension operates with an
+    API prefix configuration matching the following:
+
+    .. code-block:: python
+
+        confluence_publish_override_api_prefix = {
+            'v1': 'rest/api/',
+            'v2': 'api/v2/',
+        }
+
+    Users may define a dictionary using |confluence_api_mode|_ values for
+    keys, followed by a prefix override for their environment. For example,
+    to disable prefixes for any API v1 request, the following may be used:
+
+    .. code-block:: python
+
+        confluence_publish_override_api_prefix = {
+            'v1': '',
+        }
+
 .. confval:: confluence_parent_override_transform
 
     .. versionadded:: 2.2
@@ -2071,6 +2114,12 @@ Deprecated options
 
     See also |confluence_parent_page|_.
 
+.. confval:: confluence_publish_disable_api_prefix
+
+    .. versionchanged:: 2.5
+
+    This option has been replaced by |confluence_publish_override_api_prefix|_.
+
 .. confval:: confluence_publish_subset
 
     .. versionchanged:: 1.3

sphinxcontrib/confluencebuilder/__init__.py

@@ -115,6 +115,8 @@ def setup(app):
     cm.add_conf_bool('singleconfluence_toctree', 'singleconfluence')
 
     # (configuration - publishing)
+    # API mode to use for REST calls.
+    cm.add_conf('confluence_api_mode')
     # Request for publish password to come from interactive session.
     cm.add_conf_bool('confluence_ask_password')
     # Request for publish username to come from interactive session.
@@ -195,12 +197,12 @@ def setup(app):
     cm.add_conf('confluence_publish_denylist')
     # Whether to check for changes on remote before publishing.
     cm.add_conf_bool('confluence_publish_force')
-    # Disable adding `rest/api` to REST requests.
-    cm.add_conf_bool('confluence_publish_disable_api_prefix')
     # Header(s) to use for Confluence REST interaction.
     cm.add_conf('confluence_publish_headers')
     # Whether to publish a generated intersphinx database to the root document
     cm.add_conf_bool('confluence_publish_intersphinx')
+    # Override the path prefixes for various REST API requests.
+    cm.add_conf('confluence_publish_override_api_prefix')
     # Manipulate a requests instance.
     cm.add_conf('confluence_request_session_override')
     # Authentication passthrough for Confluence REST interaction.
@@ -263,6 +265,8 @@ def setup(app):
     cm.add_conf_bool('confluence_adv_permit_raw_html')
     # replaced by confluence_root_homepage
     cm.add_conf('confluence_master_homepage')
+    # replaced by confluence_publish_override_api_prefix
+    cm.add_conf_bool('confluence_publish_disable_api_prefix')
     # replaced by confluence_publish_allowlist
     cm.add_conf('confluence_publish_subset')
     # replaced by confluence_purge_from_root

sphinxcontrib/confluencebuilder/cmd/report.py

@@ -152,7 +152,7 @@ def report_main(args_parser):
 
             publisher.connect()
             info += ' connected: yes\n'
-            session = publisher.rest_client.session
+            session = publisher.rest.session
         except Exception:  # noqa: BLE001
             sys.stdout.flush()
             logger.error(traceback.format_exc())

sphinxcontrib/confluencebuilder/config/checks.py

@@ -2,6 +2,7 @@
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
 from pathlib import Path
+from sphinxcontrib.confluencebuilder.config.exceptions import ConfluenceApiModeConfigError
 from sphinxcontrib.confluencebuilder.config.exceptions import ConfluenceCleanupSearchModeConfigError
 from sphinxcontrib.confluencebuilder.config.exceptions import ConfluenceClientCertBadTupleConfigError
 from sphinxcontrib.confluencebuilder.config.exceptions import ConfluenceClientCertMissingCertConfigError
@@ -37,6 +38,7 @@
 from sphinxcontrib.confluencebuilder.config.notifications import warnings
 from sphinxcontrib.confluencebuilder.config.validation import ConfigurationValidation
 from sphinxcontrib.confluencebuilder.debug import PublishDebug
+from sphinxcontrib.confluencebuilder.std.confluence import API_MODES
 from sphinxcontrib.confluencebuilder.std.confluence import EDITORS
 from sphinxcontrib.confluencebuilder.util import handle_cli_file_subset
 from requests.auth import AuthBase
@@ -112,6 +114,17 @@ def validate_configuration(builder):
 
     # ##################################################################
 
+    # confluence_api_mode
+    validator.conf('confluence_api_mode') \
+             .string()
+
+    if config.confluence_api_mode:
+        if config.confluence_api_mode not in API_MODES:
+            modes = '\n - '.join(API_MODES)
+            raise ConfluenceApiModeConfigError(modes)
+
+    # ##################################################################
+
     # confluence_append_labels
     validator.conf('confluence_append_labels') \
              .bool()
@@ -539,6 +552,12 @@ def conf_translate(value):
 
     # ##################################################################
 
+    # confluence_publish_orphan_container
+    validator.conf('confluence_publish_override_api_prefix') \
+             .dict_str_str()
+
+    # ##################################################################
+
     # confluence_publish_postfix
     validator.conf('confluence_publish_postfix') \
              .string()

sphinxcontrib/confluencebuilder/config/defaults.py

@@ -108,6 +108,16 @@ def apply_defaults(builder):
     if conf.confluence_publish_orphan is None:
         conf.confluence_publish_orphan = True
 
+    if conf.confluence_publish_override_api_prefix is None:
+        # confluence_publish_disable_api_prefix is deprecated, but we will
+        # use its presence to configure v1 api for old config support
+        if conf.confluence_publish_disable_api_prefix:
+            conf.confluence_publish_override_api_prefix = {
+                'v1': '',
+            }
+        else:
+            conf.confluence_publish_override_api_prefix = {}
+
     if conf.confluence_remove_title is None:
         conf.confluence_remove_title = True
 

sphinxcontrib/confluencebuilder/config/exceptions.py

@@ -9,6 +9,17 @@ class ConfluenceConfigError(ConfluenceError, ConfigError):
     pass
 
 
+class ConfluenceApiModeConfigError(ConfluenceConfigError):
+    def __init__(self, modes):
+        super().__init__(f'''\
+invalid api version provided in confluence_api_mode
+
+The following API modes are supported:
+
+ - {modes}
+''')
+
+
 class ConfluenceCleanupSearchModeConfigError(ConfluenceConfigError):
     def __init__(self, msg):
         super().__init__(f'''\

sphinxcontrib/confluencebuilder/config/notifications.py

@@ -22,6 +22,8 @@
         'option does nothing',
     'confluence_parent_page_id_check':
         '"confluence_parent_page" now accepts a page id',
+    'confluence_publish_disable_api_prefix':
+        'use "confluence_publish_override_api_prefix" instead',
     'confluence_publish_subset':
         'use "confluence_publish_allowlist" instead',
     'confluence_purge_from_master':