doc: document new page/attachment events

Adds documentation on the recently added events with publishing pages
and attachments. This also includes an update to the metadata directive
of the recently supported GUID option.

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

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