Merge pull request #1055 from sphinx-contrib/introduce-page-id-events

Introduce publish page id events

doc/directives.rst

@@ -203,6 +203,7 @@ Common
 
     .. versionadded:: 1.3
     .. versionchanged:: 2.2 Added ``editor`` and ``full-width`` support.
+    .. versionchanged:: 2.8 Added ``guid`` support.
 
     The ``confluence_metadata`` directive allows a user to define metadata
     information to be added during a publish event. This directive supports the
@@ -237,6 +238,13 @@ Common
 
         See also :lref:`confluence_full_width`.
 
+    .. rst:directive:option:: guid: value
+        :type: string
+
+        Assign a user-managed GUID value for a page. This value can be
+        shared in a subset of :doc:`events <events>` generated by this
+        extension.
+
     .. rst:directive:option:: labels: value
         :type: space separated strings
 

doc/events.rst

@@ -6,6 +6,29 @@ The following outlines additional `events`_ supported by this extension.
 Generic events
 --------------
 
+.. event:: confluence-publish-attachment (app, docname, key, aid, meta)
+
+   :param app: :class:`.Sphinx`
+   :param docname: ``str`` of the document name
+   :param key: ``str`` of the attachment key
+   :param aid: ``int`` of the upload id of the published attachment
+   :param meta: ``dict`` of additional metadata for this event
+
+   Emitted when this extension has completed the upload of an attachment.
+
+   .. versionadded:: 2.8
+
+.. event:: confluence-publish-page (app, docname, pid, meta)
+
+   :param app: :class:`.Sphinx`
+   :param docname: ``str`` of the document name
+   :param pid: ``int`` of the upload id of the published page
+   :param meta: ``dict`` of additional metadata for this event
+
+   Emitted when this extension has completed the upload of a document.
+
+   .. versionadded:: 2.8
+
 .. event:: confluence-publish-point (app, point_url)
 
    :param app: :class:`.Sphinx`
@@ -16,6 +39,24 @@ Generic events
 
    .. versionadded:: 2.6
 
+Advanced events
+---------------
+
+.. event:: confluence-publish-override-pageid (app, docname, meta)
+
+   :param app: :class:`.Sphinx`
+   :param docname: ``str`` of the document name
+   :param meta: ``dict`` of additional metadata for this event
+   :returns: ``int | None`` of the new page identifier
+
+   Emitted when this extension is about to determine the page identifier
+   to publish a document. A configuration and register this event and
+   return a new identifier to use for a page. If ``None`` is returned,
+   the extension will operate in the same manner as if no override was
+   provided.
+
+   .. versionadded:: 2.8
+
 .. references ------------------------------------------------------------------
 
 .. _events: https://www.sphinx-doc.org/en/master/extdev/event_callbacks.html

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,
     }