From ea28688be57ab17ef79884bd8497e29fabf17de2 Mon Sep 17 00:00:00 2001 From: James Knight Date: Mon, 1 Jul 2024 12:44:47 -0400 Subject: [PATCH 1/2] cleanup publish debug options (format/presentation) Updating the configuration handling of publish debugging options to promote the uses of dashes of underscores (e.g. `headers-and-data` over `headers_and_data`). Both values are still accepted, but the dash variant will be the value shown in documentation. This commit also adjusts the configuration check to explicitly list supported options. The previous use of populating values from the enumeration does not work for all desired entries. Best to list the explicit values we want to inform a user on. Signed-off-by: James Knight --- sphinxcontrib/confluencebuilder/config/checks.py | 4 +--- sphinxcontrib/confluencebuilder/config/defaults.py | 3 ++- sphinxcontrib/confluencebuilder/config/exceptions.py | 7 +++++-- sphinxcontrib/confluencebuilder/config/validation.py | 2 +- 4 files changed, 9 insertions(+), 7 deletions(-) diff --git a/sphinxcontrib/confluencebuilder/config/checks.py b/sphinxcontrib/confluencebuilder/config/checks.py index 44e3d25b..2c1e31fb 100644 --- a/sphinxcontrib/confluencebuilder/config/checks.py +++ b/sphinxcontrib/confluencebuilder/config/checks.py @@ -533,15 +533,13 @@ def conf_translate(value): # ################################################################## # confluence_publish_debug - opts = PublishDebug._member_names_ # pylint: disable=no-member try: validator.conf('confluence_publish_debug').bool() # deprecated except ConfluenceConfigError: try: validator.conf('confluence_publish_debug').enum(PublishDebug) except ConfluenceConfigError as ex: - opts_str = '\n - '.join(opts) - raise ConfluencePublishDebugConfigError(ex, opts_str) from ex + raise ConfluencePublishDebugConfigError(ex) from ex # ################################################################## diff --git a/sphinxcontrib/confluencebuilder/config/defaults.py b/sphinxcontrib/confluencebuilder/config/defaults.py index aec7c61e..90cfcca5 100644 --- a/sphinxcontrib/confluencebuilder/config/defaults.py +++ b/sphinxcontrib/confluencebuilder/config/defaults.py @@ -107,7 +107,8 @@ def apply_defaults(builder): if publish_debug is True: conf.confluence_publish_debug = PublishDebug.urllib3 elif isinstance(publish_debug, str) and publish_debug: - conf.confluence_publish_debug = PublishDebug[publish_debug.lower()] + raw_debug = publish_debug.replace('-', '_').lower() + conf.confluence_publish_debug = PublishDebug[raw_debug] else: conf.confluence_publish_debug = PublishDebug.none diff --git a/sphinxcontrib/confluencebuilder/config/exceptions.py b/sphinxcontrib/confluencebuilder/config/exceptions.py index a9c88a01..c79cc9f5 100644 --- a/sphinxcontrib/confluencebuilder/config/exceptions.py +++ b/sphinxcontrib/confluencebuilder/config/exceptions.py @@ -229,7 +229,7 @@ def __init__(self): class ConfluencePublishDebugConfigError(ConfluenceConfigError): - def __init__(self, msg, opts): + def __init__(self, msg): super().__init__(f'''\ {msg} @@ -237,7 +237,10 @@ def __init__(self, msg, opts): debugging. Accepted values include: - all - - {opts} + - deprecated + - headers + - headers-and-data + - urllib3 ''') diff --git a/sphinxcontrib/confluencebuilder/config/validation.py b/sphinxcontrib/confluencebuilder/config/validation.py index 9f084a8b..b6fa6fb6 100644 --- a/sphinxcontrib/confluencebuilder/config/validation.py +++ b/sphinxcontrib/confluencebuilder/config/validation.py @@ -218,7 +218,7 @@ def enum(self, etype): if value is not None and not isinstance(value, etype): try: - value = etype[value.lower()] + value = etype[value.replace('-', '_').lower()] except (AttributeError, KeyError) as ex: msg = f'{self.key} is not an enumeration ({etype.__name__})' raise ConfluenceConfigError(msg) from ex From 2fcbbfa14a86b7a03b9482ad166dc83d47470946 Mon Sep 17 00:00:00 2001 From: James Knight Date: Mon, 1 Jul 2024 12:45:02 -0400 Subject: [PATCH 2/2] doc: promote an alternative headers-and-data format for publish-debug The option `headers-and-data` is preferred value for the debugging mode; updating documentation to reflect this. Signed-off-by: James Knight --- doc/configuration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/configuration.rst b/doc/configuration.rst index 512adf39..cd6c2b85 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -1524,7 +1524,7 @@ Advanced publishing configuration .. versionchanged:: 2.6 - Introduce the ``headers_and_data`` option. + Introduce the ``headers-and-data`` option. .. warning:: @@ -1544,7 +1544,7 @@ Advanced publishing configuration - ``deprecated``: Log warnings when a deprecated API call is used (*for development purposes*). - ``headers``: Log requests and responses, including their headers. - - ``headers_and_data``: Log header data along with request/response bodies. + - ``headers-and-data``: Log header data along with request/response bodies. - ``urllib3``: Enable urllib3 library debugging messages. An example debugging configuration is as follows: