Merge pull request #1162 from stibus/feature/configurableHashModifier

Add configuration option for hash modifier

Author: jdknight

doc/configuration.rst

@@ -1103,15 +1103,18 @@ Publishing configuration
 
     Supported placeholders:
 
-    * ``{hash}`` - Create a reproducible hash given the title and location
-      based from the project root. Using this placeholder provides an option
-      for allowing pages with the same title to be pushed to the same
-      Confluence space without needing to manually add an index to the title.
+    * ``{hash}`` - Create a reproducible hash given the ``docname`` (name and
+      location of the document source based from the project root) and the value
+      of :lref:`confluence_publish_postfix_hash_modifier`. Using this
+      placeholder provides an option for allowing pages with the same title to
+      be pushed to the same Confluence space without needing to manually add an
+      index to the title.
 
     By default, no postfix is used. See also:
 
     - :lref:`confluence_ignore_titlefix_on_index`
     - :lref:`confluence_publish_prefix`
+    - :lref:`confluence_publish_postfix_hash_modifier`
 
     .. versionadded:: 1.2
     .. versionchanged:: 1.9 Support for the ``{hash}`` placeholder.
@@ -1785,6 +1788,38 @@ Advanced publishing configuration
 
     .. versionadded:: 2.1
 
+.. _confluence_publish_postfix_hash_modifier:
+
+.. confval:: confluence_publish_postfix_hash_modifier
+
+    The hash for :lref:`confluence_publish_postfix` is computed from the
+    ``docname`` (name and location of the document source based from the
+    project root) and the value given here. The default value is:
+
+    .. code-block:: python
+
+        conf.confluence_publish_postfix_hash_modifier = (
+            str(conf.project)
+            + str(conf.confluence_parent_page)
+            + str(conf.confluence_publish_root)
+        )
+
+    Modify this value if you want the generated hashes to be independent of:
+
+    * ``project``
+    * :lref:`confluence_parent_page`
+    * :lref:`confluence_publish_root`
+
+    This can be helpful when your project name or the title of the parent page
+    have changed but you would like to retain the hash values. Thereby the page
+    contents may be updated without breaking links from other Confluence pages.
+
+    See also:
+
+    - :lref:`confluence_publish_postfix`
+
+    .. versionadded:: 3.0
+
 .. _confluence_publish_override_api_prefix:
 
 .. confval:: confluence_publish_override_api_prefix

sphinxcontrib/confluencebuilder/__init__.py

@@ -247,6 +247,8 @@ def setup(app):
     cm.add_conf_int('confluence_publish_orphan_container')
     # Override the path prefixes for various REST API requests.
     cm.add_conf('confluence_publish_override_api_prefix')
+    # Modifier for postfix hash of published pages.
+    cm.add_conf('confluence_publish_postfix_hash_modifier', 'confluence')
     # Number of attempts permitted when trying to retry a failed API request
     cm.add_conf('confluence_publish_retry_attempts')
     # Duration (in seconds) between retrying failed API requests

sphinxcontrib/confluencebuilder/config/checks.py

@@ -573,6 +573,12 @@ def conf_translate(value):
 
     # ##################################################################
 
+    # confluence_publish_postfix_hash_modifier
+    validator.conf('confluence_publish_postfix_hash_modifier') \
+             .string()
+
+    # ##################################################################
+
     # confluence_publish_prefix
     validator.conf('confluence_publish_prefix') \
              .string()

sphinxcontrib/confluencebuilder/config/defaults.py

@@ -128,6 +128,13 @@ def apply_defaults(app):
     if conf.confluence_publish_override_api_prefix is None:
         conf.confluence_publish_override_api_prefix = {}
 
+    if conf.confluence_publish_postfix_hash_modifier is None:
+        conf.confluence_publish_postfix_hash_modifier = (
+            str(conf.project)
+            + str(conf.confluence_parent_page)
+            + str(conf.confluence_publish_root)
+        )
+
     if conf.confluence_remove_title is None:
         conf.confluence_remove_title = True
 

sphinxcontrib/confluencebuilder/state.py

@@ -257,8 +257,5 @@ def _create_docname_unique_hash(docname: str, config) -> str:
         Create a unique(ish) hash for the given source file to avoid collisions
         when pushing pages to confluence.
         """
-        prehash = docname
-        prehash += str(config.project)
-        prehash += str(config.confluence_parent_page)
-        prehash += str(config.confluence_publish_root)
+        prehash = docname + str(config.confluence_publish_postfix_hash_modifier)
         return hashlib.sha1(prehash.encode()).hexdigest()  # noqa: S324

tests/unit-tests/test_config_postfix_formatting.py

@@ -10,8 +10,17 @@
 
 
 class TestCreateDocnameUniqueHash(ConfluenceTestCase):
+    def _build_postfix_hash_modifier(self):
+        conf = self.config
+        conf.confluence_publish_postfix_hash_modifier = (
+            str(conf.project)
+            + str(conf.confluence_parent_page)
+            + str(conf.confluence_publish_root)
+        )
+
     def test_no_parent_or_root_page_or_project_configured(self):
         test_docname = 'docs/test_file.rst'
+        self._build_postfix_hash_modifier()
         hv = ConfluenceState._create_docname_unique_hash(
             docname=test_docname, config=self.config)
         self.assertEqual(hv, '75b0047d7552a5e4d91481e992f5ed339d868b3c')
@@ -20,6 +29,7 @@ def test_parent_page_configured(self):
         test_docname = 'docs/test_file.rst'
         config = self.config
         config['confluence_parent_page'] = 'parent_page'
+        self._build_postfix_hash_modifier()
         hv = ConfluenceState._create_docname_unique_hash(
             docname=test_docname, config=self.config)
         self.assertEqual(hv, '9ca6dcc0b0e9eff175f1182ed75a2c43f359ed24')
@@ -28,6 +38,7 @@ def test_publish_root_configured(self):
         test_docname = 'docs/test_file.rst'
         config = self.config
         config['confluence_publish_root'] = 'publish_root'
+        self._build_postfix_hash_modifier()
         hv = ConfluenceState._create_docname_unique_hash(
             docname=test_docname, config=self.config)
         self.assertEqual(hv, '02fe177ef99b746ed60cb1959d6134d3ea54fab9')
@@ -36,6 +47,7 @@ def test_project_configured(self):
         test_docname = 'docs/test_file.rst'
         config = self.config
         config['project'] = 'grand_project'
+        self._build_postfix_hash_modifier()
         hv = ConfluenceState._create_docname_unique_hash(
             docname=test_docname, config=self.config)
         self.assertEqual(hv, '67e8ac11ab088e763c3cf2e577037b510a54ba41')