Extensions

The Sphinx Confluence Builder is powered by Sphinx. There are several ways individual projects may extend their configuration or use other extensions to improve the processing and generation of their documentation.

For users new to Sphinx, it is recommended to read Sphinx’s documentation on extensions:

Developers or advanced users are recommended to use official Sphinx API calls for any modifications that are applicable when using the Sphinx Confluence Builder extension. Users are welcome to inspect this extension’s code for any custom tweaks desired for their project.

The following shows an example modification for a project to support a custom node type that is not supported by this extension. Users can use Sphinx.add_node to help register support for custom nodes. The keyword to use for this extension is confluence. If another extension defines a node custom_node, the following shows some example code to start supporting this node with Sphinx Confluence Builder:

def setup(app):
    app.add_node(
        custom_node,
        confluence=(visit_custom_node, depart_custom_node),
    )

def visit_custom_node(self, node):
    self.body.append('[pre]')
    self.context.append('[post]')

def depart_custom_node(self, node):
    self.body.append(self.context.pop())

Confluence Storage Format Translator Helpers

When extending this extension or adding more advanced configurations, a series of helper calls are available for use. API calls may evolve over time as this extension is maintained. The following methods are available for a ConfluenceStorageFormatTranslator translator.

start_tag(self, node, tag, suffix=None, empty=False, **kwargs)

A helper used to return content to be appended to a document which initializes the start of a storage format element (i.e. generates a start tag). The element of type tag will be initialized. This method may use the provided node to tweak the final content. Non-empty tags should be used with a respective end_tag() call.

def visit_custom_node(self, node):
    self.body.append(self.start_tag(node, 'p'))
    self.context.append(self.end_tag(node))

def depart_custom_node(self, node):
    self.body.append(self.context.pop())
Parameters:

  • node – the node processing the start-tag

  • tag – the type of tag

  • suffix (optional) – the suffix to add (defaults to nothing)

  • empty (optional) – tag will not hold child nodes (defaults to False)

  • **kwargs (optional) – dictionary of attributes to include in the tag

Returns:

the content

end_tag(self, node, suffix=None)

A helper used to return content to be appended to a document which finalizes a storage format element (i.e. generates an end tag). This method should be used to help close a start_tag() call (with the exception of when start_tag() is invoked with empty=True).

Parameters:

  • node – the node processing the end-tag

  • suffix (optional) – the suffix to add (defaults to newline)

Returns:

the content

start_ac_image(self, node, **kwargs)

A helper used to return content to be appended to a document which initializes the start of a storage format image element. The ac:image element will be initialized. This method may use provided node to tweak the final content. This call should be used with a respective end_ac_image() call.

Parameters:

node – the node processing the image

Returns:

the content

end_ac_image(self, node)

A helper used to return content to be appended to a document which finalizes a storage format image element. This method should be used to help close a start_ac_image() call.

Parameters:

node – the node processing the image

Returns:

the content

start_ac_link(self, node, anchor=None, appearance=None)

A helper used to return content to be appended to a document which initializes the start of a storage format link element of a specific type. The ac:link element will be initialized. This method may use provided node to tweak the final content. This call should be used with a respective end_ac_link() call.

Parameters:

  • node – the node processing the link

  • anchor (optional) – the anchor value to use (defaults to None)

  • appearance (optional) – card appearance to use (defaults to None)

Returns:

the content

end_ac_link(self, node)

A helper used to return content to be appended to a document which finalizes a storage format link element. This method should be used to help close a start_ac_link() call.

Parameters:

node – the node processing the link

Returns:

the content

start_ac_link_body(self, node)

A helper used to return content to be appended to a document which initializes the start of a storage format link-body element. The ac:link-body element will be initialized. This method may use provided node to tweak the final content. This call should be used with a respective end_ac_link_body() call.

Parameters:

node – the node processing the macro

Returns:

the content

end_ac_link_body(self, node)

A helper used to return content to be appended to a document which finalizes a storage format link-body element. This method should be used to help close a start_ac_link_body() call.

Parameters:

node – the node processing the macro

Returns:

the content

start_ac_macro(self, node, type_, empty=False)

A helper used to return content to be appended to a document which initializes the start of a storage format macro element of a specific type. The ac:structured-macro element will be initialized. This method may use provided node to tweak the final content. This call should be used with a respective end_ac_macro() call.

Parameters:

  • node – the node processing the macro

  • type – the type of macro

  • empty (optional) – tag will not hold child nodes (defaults to False)

Returns:

the content

build_ac_param(self, node, name, value)

A helper used to return content to be appended to a document which builds a complete storage format parameter element. The ac:parameter element will be built. This method may use provided node to tweak the final content.

Parameters:

  • node – the node processing the parameter

  • name – the parameter name

  • value – the value for the parameter

Returns:

the content

end_ac_macro(self, node, suffix=None)

A helper used to return content to be appended to a document which finalizes a storage format macro element. This method should be used to help close a start_ac_macro() call (with the exception of when start_ac_macro() is invoked with empty=True).

Parameters:

  • node – the node processing the macro

  • suffix (optional) – the suffix to add (defaults to newline)

Returns:

the content

start_ac_plain_text_body_macro(self, node)

A helper used to return content to be appended to a document which initializes the start of a storage format plain-text-body element. The ac:plain-text-body element will be initialized. This method may use provided node to tweak the final content. This call should be used with a respective end_ac_plain_text_body_macro() call.

Parameters:

node – the node processing the macro

Returns:

the content

end_ac_plain_text_body_macro(self, node)

A helper used to return content to be appended to a document which finalizes a storage format plain-text-body element. This method should be used to help close a start_ac_plain_text_body_macro() call.

Parameters:

node – the node processing the macro

Returns:

the content

start_ac_plain_text_link_body_macro(self, node)

A helper used to return content to be appended to a document which initializes the start of a storage format plain-text-body element. The ac:plain-text-body element will be initialized. This method may use provided node to tweak the final content. This call should be used with a respective end_ac_plain_text_link_body_macro() call.

Parameters:

node – the node processing the macro

Returns:

the content

end_ac_plain_text_link_body_macro(self, node)

A helper used to return content to be appended to a document which finalizes a storage format plain-text-link-body element. This method should be used to help close a start_ac_plain_text_link_body_macro() call.

Parameters:

node – the node processing the macro

Returns:

the content

start_ac_rich_text_body_macro(self, node)

A helper used to return content to be appended to a document which initializes the start of a storage format rich-text-body element. The ac:rich-text-body element will be initialized. This method may use provided node to tweak the final content. This call should be used with a respective end_ac_rich_text_body_macro() call.

Parameters:

node – the node processing the macro

Returns:

the content

end_ac_rich_text_body_macro(self, node)

A helper used to return content to be appended to a document which finalizes a storage format rich-text-body element. This method should be used to help close a start_ac_rich_text_body_macro() call.

Parameters:

node – the node processing the macro

Returns:

the content

start_adf_content(self, node)

A helper used to return content to be appended to a document which initializes the start of a storage format adf-content element. The ac:adf-content element will be initialized. This method may use provided node to tweak the final content. This call should be used with a respective end_adf_content() call.

Parameters:

node – the node processing the macro

Returns:

the content

end_adf_content(self, node, suffix=None)

A helper used to return content to be appended to a document which finalizes a storage format adf-content element. This method should be used to help close a start_adf_content() call.

Parameters:

  • node – the node processing the macro

  • suffix (optional) – the suffix to add (defaults to newline)

Returns:

the content

start_adf_extension(self, node)

A helper used to return content to be appended to a document which initializes the start of a storage format adf-extension element. The ac:adf-extension element will be initialized. This call should be used with a respective start_adf_extension() call.

Parameters:

node – the node processing the macro

Returns:

the content

build_adf_attribute(self, node, name, value)

A helper used to return content to be appended to a document which builds a complete storage format parameter element. The ac:adf-attribute element will be built. This method may use provided node to tweak the final content.

Parameters:

  • node – the node processing the parameter

  • name – the parameter name

  • value – the value for the parameter

Returns:

the content

end_adf_extension(self, node, suffix=None)

A helper used to return content to be appended to a document which finalizes a storage format adf-extension element. This method should be used to help close a start_adf_extension() call.

Parameters:

  • node – the node processing the macro

  • suffix (optional) – the suffix to add (defaults to newline)

Returns:

the content

start_adf_node(self, node, type_, empty=False)

A helper used to return content to be appended to a document which initializes the start of a storage format adf-node element of a specific type. The ac:adf-node element will be initialized. This method may use provided node to tweak the final content. This call should be used with a respective end_adf_node() call.

Parameters:

node – the node processing the macro

Returns:

the content

end_adf_node(self, node, suffix=None)

A helper used to return content to be appended to a document which finalizes a storage format adf-node element. This method should be used to help close a start_adf_node() call (with the exception of when start_adf_node() is invoked with empty=True).

Parameters:

  • node – the node processing the macro

  • suffix (optional) – the suffix to add (defaults to newline)

Returns:

the content

start_ri_attachment(self, node, filename)

A helper used to return content to be appended to a document which initializes the start of a storage format attachment element. The ri:attachment element will be initialized. This method may use provided node to tweak the final content.

Parameters:

  • node – the node processing the attachment

  • filename – the filename of the attachment

Returns:

the content

end_ri_attachment(self, node)

A helper used to return content to be appended to a document which finalizes a storage format attachment element. This method should be used to help close a start_ri_attachment() call.

Parameters:

node – the node processing the attachment

Returns:

the content

escape_cdata(self, data)

A helper used to return content that has been properly escaped and can be directly placed inside a CDATA container.

Parameters:

data – the text

Returns:

the escaped text