From 8d297b8cc702cfb839879def8fc2cdf0872702f1 Mon Sep 17 00:00:00 2001 From: James Knight Date: Tue, 19 Mar 2024 00:07:32 -0400 Subject: [PATCH 1/3] support custom page generation notice Allows a user to configure `confluence_page_generation_notice` with a custom message, which can be used instead of the embedded string for the added "page is generated" message. Signed-off-by: James Knight --- sphinxcontrib/confluencebuilder/__init__.py | 2 +- sphinxcontrib/confluencebuilder/config/checks.py | 10 ++++++++-- sphinxcontrib/confluencebuilder/config/exceptions.py | 12 ++++++++++++ .../storage/templates/domainindex.html | 6 +++++- .../storage/templates/domainindex_v2.html | 6 +++++- .../storage/templates/genindex.html | 6 +++++- .../storage/templates/genindex_v2.html | 6 +++++- .../confluencebuilder/storage/templates/search.html | 6 +++++- .../confluencebuilder/storage/translator.py | 8 ++++++-- 9 files changed, 52 insertions(+), 10 deletions(-) diff --git a/sphinxcontrib/confluencebuilder/__init__.py b/sphinxcontrib/confluencebuilder/__init__.py index 7d53a9f7..665c81dd 100644 --- a/sphinxcontrib/confluencebuilder/__init__.py +++ b/sphinxcontrib/confluencebuilder/__init__.py @@ -100,7 +100,7 @@ def setup(app): # Enablement of a generated search documents cm.add_conf_bool('confluence_include_search', 'confluence') # Enablement of a "page generated" notice. - cm.add_conf_bool('confluence_page_generation_notice', 'confluence') + cm.add_conf('confluence_page_generation_notice', 'confluence') # Enablement of publishing pages into a hierarchy from a root toctree. cm.add_conf_bool('confluence_page_hierarchy', 'confluence') # Show previous/next buttons (bottom, top, both, None). diff --git a/sphinxcontrib/confluencebuilder/config/checks.py b/sphinxcontrib/confluencebuilder/config/checks.py index 2afd30db..476cb7a1 100644 --- a/sphinxcontrib/confluencebuilder/config/checks.py +++ b/sphinxcontrib/confluencebuilder/config/checks.py @@ -16,6 +16,7 @@ from sphinxcontrib.confluencebuilder.config.exceptions import ConfluenceJiraServersConfigError from sphinxcontrib.confluencebuilder.config.exceptions import ConfluenceLatexMacroInvalidConfigError from sphinxcontrib.confluencebuilder.config.exceptions import ConfluenceLatexMacroMissingKeysConfigError +from sphinxcontrib.confluencebuilder.config.exceptions import ConfluencePageGenerationNoticeConfigError from sphinxcontrib.confluencebuilder.config.exceptions import ConfluenceParentPageConfigError from sphinxcontrib.confluencebuilder.config.exceptions import ConfluencePermitRawHtmlConfigError from sphinxcontrib.confluencebuilder.config.exceptions import ConfluencePrevNextButtonsLocationConfigError @@ -444,8 +445,13 @@ def validate_configuration(builder): # ################################################################## # confluence_page_generation_notice - validator.conf('confluence_page_generation_notice') \ - .bool() + try: + validator.conf('confluence_page_generation_notice').bool() + except ConfluenceConfigError: + try: + validator.conf('confluence_page_generation_notice').string() + except ConfluenceConfigError as ex: + raise ConfluencePageGenerationNoticeConfigError from ex # ################################################################## diff --git a/sphinxcontrib/confluencebuilder/config/exceptions.py b/sphinxcontrib/confluencebuilder/config/exceptions.py index 7fe0c13a..50be10b6 100644 --- a/sphinxcontrib/confluencebuilder/config/exceptions.py +++ b/sphinxcontrib/confluencebuilder/config/exceptions.py @@ -154,6 +154,18 @@ def __init__(self, keys): ''') +class ConfluencePageGenerationNoticeConfigError(ConfluenceConfigError): + def __init__(self): + super().__init__('''\ +confluence_page_generation_notice is not a boolean or a string + +The option 'confluence_page_generation_notice' has been provided to +indicate that a notice should be added at the top of each page about +pages being generated. This value can either be set to `True` or +configured with the message to inform users. +''') + + class ConfluenceParentPageConfigError(ConfluenceConfigError): def __init__(self): super().__init__('''\ diff --git a/sphinxcontrib/confluencebuilder/storage/templates/domainindex.html b/sphinxcontrib/confluencebuilder/storage/templates/domainindex.html index 86b5ba71..8fdf37da 100644 --- a/sphinxcontrib/confluencebuilder/storage/templates/domainindex.html +++ b/sphinxcontrib/confluencebuilder/storage/templates/domainindex.html @@ -8,7 +8,11 @@ {%- if pagegen_notice -%}
- {{ L('This page has been automatically generated.') }} + {%- if pagegen_notice is sameas true -%} + {{ L('This page has been automatically generated.') }} + {%- else -%} + {{ L(pagegen_notice|e)}} + {%- endif %}
diff --git a/sphinxcontrib/confluencebuilder/storage/templates/domainindex_v2.html b/sphinxcontrib/confluencebuilder/storage/templates/domainindex_v2.html index c4f6cf51..908a466c 100644 --- a/sphinxcontrib/confluencebuilder/storage/templates/domainindex_v2.html +++ b/sphinxcontrib/confluencebuilder/storage/templates/domainindex_v2.html @@ -8,7 +8,11 @@ {%- if pagegen_notice -%}
- {{ L('This page has been automatically generated.') }} + {%- if pagegen_notice is sameas true -%} + {{ L('This page has been automatically generated.') }} + {%- else -%} + {{ L(pagegen_notice|e)}} + {%- endif %}
diff --git a/sphinxcontrib/confluencebuilder/storage/templates/genindex.html b/sphinxcontrib/confluencebuilder/storage/templates/genindex.html index 9130901e..511feff2 100644 --- a/sphinxcontrib/confluencebuilder/storage/templates/genindex.html +++ b/sphinxcontrib/confluencebuilder/storage/templates/genindex.html @@ -34,7 +34,11 @@ {%- if pagegen_notice -%}
- {{ L('This page has been automatically generated.') }} + {%- if pagegen_notice is sameas true -%} + {{ L('This page has been automatically generated.') }} + {%- else -%} + {{ L(pagegen_notice|e)}} + {%- endif %}
diff --git a/sphinxcontrib/confluencebuilder/storage/templates/genindex_v2.html b/sphinxcontrib/confluencebuilder/storage/templates/genindex_v2.html index b85aaaf6..a9549057 100644 --- a/sphinxcontrib/confluencebuilder/storage/templates/genindex_v2.html +++ b/sphinxcontrib/confluencebuilder/storage/templates/genindex_v2.html @@ -34,7 +34,11 @@ {%- if pagegen_notice -%}
- {{ L('This page has been automatically generated.') }} + {%- if pagegen_notice is sameas true -%} + {{ L('This page has been automatically generated.') }} + {%- else -%} + {{ L(pagegen_notice|e)}} + {%- endif %}
diff --git a/sphinxcontrib/confluencebuilder/storage/templates/search.html b/sphinxcontrib/confluencebuilder/storage/templates/search.html index ac8da5b1..28ae5a17 100644 --- a/sphinxcontrib/confluencebuilder/storage/templates/search.html +++ b/sphinxcontrib/confluencebuilder/storage/templates/search.html @@ -7,7 +7,11 @@ {%- if pagegen_notice -%}
- {{ L('This page has been automatically generated.') }} + {%- if pagegen_notice is sameas true -%} + {{ L('This page has been automatically generated.') }} + {%- else -%} + {{ L(pagegen_notice|e)}} + {%- endif %}
diff --git a/sphinxcontrib/confluencebuilder/storage/translator.py b/sphinxcontrib/confluencebuilder/storage/translator.py index 483889dd..fff5acc3 100644 --- a/sphinxcontrib/confluencebuilder/storage/translator.py +++ b/sphinxcontrib/confluencebuilder/storage/translator.py @@ -2433,8 +2433,12 @@ def visit_confluence_page_generation_notice(self, node): 'style': 'color: #707070; font-size: 12px;', })) - self.body.append(self.encode( - L('This page has been automatically generated.'))) + if self.builder.config.confluence_page_generation_notice is True: + notice_msg = 'This page has been automatically generated.' + else: + notice_msg = self.builder.config.confluence_page_generation_notice + + self.body.append(self.encode(L(notice_msg))) if self.v2: self.body.append(self._end_tag(node, suffix='')) # sup From 4d91b298d36975cf3b9a2f7608f595d86bda9c6a Mon Sep 17 00:00:00 2001 From: James Knight Date: Tue, 19 Mar 2024 00:08:17 -0400 Subject: [PATCH 2/3] tests: add checks for updated page-gen notice values Signed-off-by: James Knight --- tests/unit-tests/test_config_checks.py | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/tests/unit-tests/test_config_checks.py b/tests/unit-tests/test_config_checks.py index 18340b30..ec5e21a0 100644 --- a/tests/unit-tests/test_config_checks.py +++ b/tests/unit-tests/test_config_checks.py @@ -8,6 +8,7 @@ from sphinx.errors import SphinxWarning from sphinxcontrib.confluencebuilder.builder import ConfluenceBuilder from sphinxcontrib.confluencebuilder.config.exceptions import ConfluenceConfigError +from sphinxcontrib.confluencebuilder.config.exceptions import ConfluencePageGenerationNoticeConfigError from sphinxcontrib.confluencebuilder.config.exceptions import ConfluencePermitRawHtmlConfigError from sphinxcontrib.confluencebuilder.config.exceptions import ConfluencePublishCleanupConflictConfigError from sphinxcontrib.confluencebuilder.config.exceptions import ConfluenceSourcelinkTypeConfigError @@ -579,6 +580,23 @@ def test_config_check_mentions(self): with self.assertRaises(ConfluenceConfigError): self._try_config() + def test_config_check_page_generation_notice(self): + self.config['confluence_page_generation_notice'] = True + self._try_config() + + self.config['confluence_page_generation_notice'] = False + self._try_config() + + self.config['confluence_page_generation_notice'] = '' + self._try_config() + + self.config['confluence_page_generation_notice'] = 'message' + self._try_config() + + self.config['confluence_page_generation_notice'] = [1, 2, 3] + with self.assertRaises(ConfluencePageGenerationNoticeConfigError): + self._try_config() + def test_config_check_parent_page(self): self.config['confluence_parent_page'] = 'dummy' self._try_config() From 0073c2aec49085d9a271e9d43a3c01216364c9c3 Mon Sep 17 00:00:00 2001 From: James Knight Date: Tue, 19 Mar 2024 00:10:16 -0400 Subject: [PATCH 3/3] doc: update page-gen notice config for new capabilities Signed-off-by: James Knight --- doc/configuration.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/doc/configuration.rst b/doc/configuration.rst index 00445cd7..7c38a77c 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -397,15 +397,24 @@ Generic configuration .. confval:: confluence_page_generation_notice .. versionadded:: 1.7 + .. versionchanged:: 2.5 Accept a string for custom notice. - A boolean value to whether or not to generate a message at the top of each - document that the page has been automatically generated. By default, this - notice is disabled with a value of ``False``. + This option can be set with a boolean value to whether or not to generate + a message at the top of each document that the page has been + automatically generated. .. code-block:: python confluence_page_generation_notice = True + Alternatively, users may set a custom message to display. + + .. code-block:: python + + confluence_page_generation_notice = 'My awesome message.' + + By default, this notice is disabled with a value of ``False``. + .. confval:: confluence_page_hierarchy .. versionchanged:: 2.0 Option is enabled by default.