Features

The following outlines the reStructuredText/Sphinx markup, configuration entries and more supported by this extension. The intent of this extension is to support various standard Sphinx features that can be rendered on a Confluence instance. Below will identify features that have been tested, planned to be implemented in the future or is not compatible with Confluence.

reStructuredText markup

Type

Notes

admonitions

Supported

bibliographic fields

Supported

block quotes

Supported

bullet lists

Supported

citations

Supported

compound paragraph

Supported

container

Unsupported.

Confluence markup does not permit the use of the class attribute for tags.

csv-table

Supported

definition lists

Supported

enumerated lists

Limited support.

Only auto-enumerator lists (#) are supported. Using other types of enumerated lists will be handled as auto-enumerators. This is a limitation in the Confluence markup.

epigraph

Supported

footnotes

Supported

highlights

Supported

hyperlink targets

Supported

images

Supported

inline markup

Supported

list-table

Supported

literal blocks

Supported

math

Supported with additional system tools.

Requires a LaTeX and dvipng/dvisvgm installation.

parsed literal block

Supported

option lists

Supported

pull-quote

Supported

raw

Supported.

Use the confluence_storage format type to inject raw data into a document.

rubric

Supported

sections

Supported

tables

Supported

transitions

Supported

(note: directive options “class” and “name” are ignored as they are not supported in a Confluence format document)

Sphinx markup

Type

Notes

centered

Supported

code

Limited support.

Supported languages (for highlighting) are limited to the languages supported by Confluence’s code block macro. This applies to a language defined in a code-block directive or set through a highlight directive.

The code-block directive contain the options emphasize-lines and lines which are not supported in the Confluence markup. The code block macro only supports a simple line numbers (configurable with the linenos option).

deprecated

Supported

download

Supported

glossary

Supported

hlist

Supported

manpage

Supported

production list

Supported

toctree

Supported

versionadded

Supported

versionchanged

Supported

(note: directive options “class” and “name” are ignored as they are not supported in a Confluence format document)

Extensions

This extension will attempt to support any extension that is integrated in Sphinx’s main source repository. The following section shows the status of each of these extensions:

Type

Notes

sphinx.ext.autodoc

Supported*.

While support for autodocs has been included in this extension, only a limited amount of examples and testing has been done to verify its capabilities. If an issue is observed when using an autodoc feature, please confirm an expected result using an html build then report the issue.

sphinx.ext.autosectionlabel

Supported

sphinx.ext.autosummary

Supported

sphinx.ext.coverage

N/A

sphinx.ext.doctest

Supported

sphinx.ext.duration

Supported

sphinx.ext.extlinks

Supported

sphinx.ext.githubpages

N/A

sphinx.ext.graphviz

Supported

sphinx.ext.ifconfig

Supported

sphinx.ext.imgconverter

N/A

sphinx.ext.imgmath

Supported

sphinx.ext.inheritance_diagram

Supported

sphinx.ext.intersphinx

Limited support.

Users should have no issues when using external modules via intersphinx_mapping. When building with publishing enabled, this extension will generate an objects.inv inventory file which can be used by other documentation sets. At this time, only document names and standard references are supported. A generated inventory file is not published to a Confluence instance.

sphinx.ext.jsmath

Unsupported.

Confluence does not support the injection of JavaScript into a page in most scenarios.

sphinx.ext.linkcode

Unsupported.

This extension only supports injecting references for the html builder.

sphinx.ext.mathjax

Unsupported.

Confluence does not support the injection of JavaScript into a page in most scenarios.

sphinx.ext.napoleon

Supported

sphinx.ext.todo

Supported

sphinx.ext.viewcode

Unsupported.

This extension only supports injecting references for the html builder.

Extensions (Third-party)

Note

Support with third-party extensions (if any) may be limited. While an extension may work with other builders (such as the html builder), it may be implemented in a way which it cannot be integrated with this extension. In addition, some features that an extension may use (e.g. using JavaScript) cannot be used with a stock Confluence instance and therefore, cannot be supported.

Atlassian Confluence Builder for Sphinx does not guarantee support for third-party extensions found outside of Sphinx’s main source repository. Changes are considered towards this extension’s processing and API to make it flexible for other extensions to integrate. Also, this extension may provide optional support for select third-party extensions (if permitted and rational), to help improve user experience.

Developers wishing to integrate a third-party extension with Atlassian Confluence Builder can either attempt to add implementation inside the third-party extension itself, propose non-intrusive changes to this extension or create a new extension which can bind both desired extensions together (e.g. sphinx-confluence-nbsphinx-test). Any changes directly submitted to be added into this extension’s repository will be limited to the arbitrary release/development windows of this extension.

The following table show a most recent state of various third-party extensions interacting with this extension:

Type

Notes

mlx.traceability

Limited support.

Formatting of content may not be as expected.

sphinx-diagrams

Supported

sphinx-gallery

Supported

sphinx-needs

Limited support.

Formatting of content may not be as expected. The needs_default_layout option may need to be tailored specifically for a Confluence build.

sphinx-toolbox

Supported

sphinxcontrib-aafig

Supported.

May require configuration of the aafig_format option.

sphinxcontrib-actdiag

Limited support.

PNGs only; cannot configure for SVG at this time.

sphinxcontrib-blockdiag

Limited support.

PNGs only; cannot configure for SVG at this time.

sphinxcontrib-drawio

Supported

sphinxcontrib-httpdomain

Supported

sphinxcontrib-kroki

Supported

sphinxcontrib-mermaid

Limited support.

Requires a PNG/SVG configuration.

sphinxcontrib-nwdiag

Limited support.

PNGs only; cannot configure for SVG at this time.

sphinxcontrib-openapi

Supported

sphinxcontrib-plantuml

Supported.

sphinxcontrib-plantuml provides its own support for this extension.

sphinxcontrib-programoutput

Supported

sphinxcontrib-seqdiag

Limited support.

PNGs only; cannot configure for SVG at this time.

sphinxcontrib-svgbob

Supported

sphinxcontrib-youtube

Supported

Other

If a feature and/or extension is not listed above, is not working as expected or brings up another concern, feel free to bring up an issue:

Atlassian Confluence Builder for Confluence - Issues