introduce publish page id events

The following introduces three new events into the extension:

- confluence-publish-attachment
- confluence-publish-page
- confluence-publish-override-pageid

These events provide two key capabilities for advanced users. First, it
provides a means to hook into the publish processing to allow reacting
to page/attachment upload events to help track what pages are published
under what page identifier. Second, it provides a hook to allow a
custom configuration to override document page identifiers if desired.
This should give more power to users who may want more control where
pages are published to for a target Confluence instance.

Signed-off-by: James Knight <[email protected]>

sphinxcontrib/confluencebuilder/__init__.py

@@ -60,6 +60,9 @@ def setup(app):
     app.add_builder(ConfluenceBuilder)
     app.add_builder(ConfluenceReportBuilder)
     app.add_builder(SingleConfluenceBuilder)
+    app.add_event('confluence-publish-attachment')
+    app.add_event('confluence-publish-override-pageid')
+    app.add_event('confluence-publish-page')
     app.add_event('confluence-publish-point')
     app.add_post_transform(ConfluenceHyperlinkCollector)
 

sphinxcontrib/confluencebuilder/builder.py

@@ -502,7 +502,19 @@ def publish_doc(self, docname, output):
 
         data = self._prepare_page_data(docname, output)
 
-        if conf.confluence_publish_root and is_root_doc:
+        metadata = self.metadata.get(docname, {})
+        docguid = metadata.get('guid')
+
+        forced_page_id = self.app.emit_firstresult(
+            'confluence-publish-override-pageid', docname, {
+                'guid': docguid,
+                'title': title,
+            })
+
+        if forced_page_id:
+            uploaded_id = self.publisher.store_page_by_id(title,
+                forced_page_id, data)
+        elif conf.confluence_publish_root and is_root_doc:
             uploaded_id = self.publisher.store_page_by_id(title,
                 conf.confluence_publish_root, data)
         else:
@@ -590,6 +602,12 @@ def publish_doc(self, docname, output):
             if uploaded_id in self.legacy_pages:
                 self.legacy_pages.remove(uploaded_id)
 
+        if uploaded_id:
+            self.app.emit('confluence-publish-page', docname, uploaded_id, {
+                'guid': docguid,
+                'title': title,
+            })
+
     def _prepare_page_data(self, docname, output):
         data = {
             'content': output,
@@ -664,6 +682,13 @@ def publish_asset(self, key, docname, output, type_, hash_):
                 if attachment_id in legacy_asset_info:
                     legacy_asset_info.pop(attachment_id, None)
 
+        if attachment_id:
+            self.app.emit('confluence-publish-attachment',
+                docname, key, attachment_id, {
+                'hash': hash_,
+                'type': type_,
+            })
+
     def publish_finalize(self):
         if self.root_doc_page_id:
             if self.config.confluence_root_homepage is True:

sphinxcontrib/confluencebuilder/directives.py

@@ -200,6 +200,7 @@ class ConfluenceMetadataDirective(Directive):
     option_spec = {
         'editor': lambda x: directives.choice(x, EDITORS),
         'full-width': lambda x: directives.choice(x, ('true', 'false')),
+        'guid': directives.unchanged,
         'labels': string_list,
     }