Merge pull request #930 from sphinx-contrib/support-custom-page-gen-n…

…otice

support custom page generation notice

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.

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).

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
 
     # ##################################################################
 

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__('''\

sphinxcontrib/confluencebuilder/storage/templates/domainindex.html

@@ -8,7 +8,11 @@
 
 {%- if pagegen_notice -%}
     <div style="color: #707070; font-size: 12px;">
-        {{ 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 %}
     </div>
 
     <hr style="clear: both; padding-top: 10px" />

sphinxcontrib/confluencebuilder/storage/templates/domainindex_v2.html

@@ -8,7 +8,11 @@
 
 {%- if pagegen_notice -%}
     <div style="color: #707070; font-size: 12px;">
-        {{ 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 %}
     </div>
 
     <hr style="clear: both; padding-top: 10px" />

sphinxcontrib/confluencebuilder/storage/templates/genindex.html

@@ -34,7 +34,11 @@
 
 {%- if pagegen_notice -%}
     <div style="color: #707070; font-size: 12px;">
-        {{ 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 %}
     </div>
 
     <hr style="clear: both; padding-top: 10px" />

sphinxcontrib/confluencebuilder/storage/templates/genindex_v2.html

@@ -34,7 +34,11 @@
 
 {%- if pagegen_notice -%}
     <div style="color: #707070; font-size: 12px;">
-        {{ 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 %}
     </div>
 
     <hr style="clear: both; padding-top: 10px" />

sphinxcontrib/confluencebuilder/storage/templates/search.html

@@ -7,7 +7,11 @@
 
 {%- if pagegen_notice -%}
     <div style="color: #707070; font-size: 12px;">
-        {{ 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 %}
     </div>
 
     <hr style="clear: both; padding-top: 10px; margin-bottom: 30px" />

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

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()