An official way to add extra Confluence nodes

[neongreen-sc]

Right now it looks like you can add extra nodes without modifying the extension, but it depends on private methods of the translator.

Example for the panel macro:

from docutils import nodes
from sphinxcontrib.confluencebuilder.storage.translator import (
    ConfluenceStorageFormatTranslator,
)

def setup(app: Sphinx):
    app.add_node(
        confluence_panel,
        confluence=(visit_confluence_panel, depart_confluence_panel),
    )

class confluence_panel(nodes.General, nodes.Element):
    pass

def visit_confluence_panel(
    self: ConfluenceStorageFormatTranslator, node: confluence_panel
):
    self.body.append(self._start_ac_macro(node, "panel"))
    if "title" in node:
        self.body.append(self._build_ac_param(node, "title", node["title"]))
    self.body.append(self._start_ac_rich_text_body_macro(node))
    self.context.append(
        self._end_ac_rich_text_body_macro(node) + self._end_ac_macro(node)
    )

def depart_confluence_panel(
    self: ConfluenceStorageFormatTranslator, node: confluence_panel
):
    self.body.append(self.context.pop())

Is there a better way to do this?

[jdknight]

The approach made is in general the way to inject custom modifications for individual documentation configurations.

If the main concern is trying to avoid the use of internal calls of this extension, an (untested) alternative would be to just perform something such as the following:

    self.body.append('<ac:structured-macro ac:name="panel">')
    if "title" in node:
        self.body.append('<ac:parameter ac:name="title">{}</ac:parameter>'.format(node["title"]))
    self.body.append('<ac:rich-text-body>')
    self.context.append('</ac:rich-text-body></ac:structured-macro>')

Calls such as _start_ac_macro, _build_ac_param, etc. were left internal solely since there was plan to support both Confluence storage and ADF formatting in this extension. Although, progression to support ADF was stopped mainly due to the confirmation that storage format was not going to be removed (at the time when they were introduced the v2 "fabric" editor).

We could look at providing "proper" API calls to help support custom modifications for users and other extensions wanting to use helper calls such as the ones mentioned.

[neongreen-sc]

For me, either proper API calls, or documentation on supporting custom Confluence nodes would be lovely. I'm worried about someone else inheriting my Sphinx code and not being able to figure out what's going on.

[jdknight]

Changes have been introduced in this extension to adjust various "internal" helper calls to be "public" calls (https://github.com/sphinx-contrib/confluencebuilder/pull/989). Also added an initial document to provide a general overview and pull documentation for the helper calls from source.