Documentation contents¶

Installing¶

Atlassian Confluence Builder for Sphinx 2.1.1 depends on:

Python 3.7+
Requests 2.14.0 or later
Sphinx 5.3+
Confluence Cloud or Server 7.13+

The recommended method of installing or upgrading is using pip:

pip install -U sphinxcontrib-confluencebuilder
 (or)
python -m pip install -U sphinxcontrib-confluencebuilder

To verify the package has been installed, the following command can be used:

python -m sphinxcontrib.confluencebuilder --version

For new users, the following provides a series of steps to assist in preparing a new environment to use this package. For users wishing to use virtualenv, please see the instructions in Installing (virtualenv).

Note

If the installation process fails with the following error “AttributeError: ‘_NamespacePath’ object has no attribute ‘sort’”, try upgrading the setuptools module:

pip install -U setuptools
 (or)
python -m pip install -U setuptools

Linux¶

While the use of Python/pip is almost consistent between Linux distributions, the following are a series of helpful steps to install this package under specific distributions of Linux. From a terminal, invoke the following commands:

Arch¶

$ sudo pacman -Sy
$ sudo pacman -S python-pip
$ pip install sphinxcontrib-confluencebuilder
$ python -m sphinxcontrib.confluencebuilder --version
sphinxcontrib.confluencebuilder <version>

CentOS¶

$ sudo yum install epel-release
$ sudo yum install python-pip
$ pip install sphinxcontrib-confluencebuilder
$ python -m sphinxcontrib.confluencebuilder --version
sphinxcontrib.confluencebuilder <version>

Fedora¶

$ sudo dnf install python-pip
$ pip install sphinxcontrib-confluencebuilder
$ python -m sphinxcontrib.confluencebuilder --version
sphinxcontrib.confluencebuilder <version>

Ubuntu¶

$ sudo apt-get update
$ sudo apt-get install python-pip
$ pip install sphinxcontrib-confluencebuilder
$ python -m sphinxcontrib.confluencebuilder --version
sphinxcontrib.confluencebuilder <version>

OS X¶

From a terminal, invoke the following commands:

$ sudo easy_install pip
$ pip install sphinxcontrib-confluencebuilder
$ python -m sphinxcontrib.confluencebuilder --version
sphinxcontrib.confluencebuilder <version>

Windows¶

If not already installed, download the most recent version of Python:

Python - Downloads

https://www.python.org/downloads/

When invoking the installer, it is recommended to select the option to “Add Python to PATH”; however, users can explicitly invoked Python from an absolute path. The remainder of these steps will assume Python is available in the path.

Open a Windows command prompt. Invoke the following:

> python -m pip install sphinxcontrib-confluencebuilder
> python -m sphinxcontrib.confluencebuilder --version
sphinxcontrib.confluencebuilder <version>

Development installation¶

To install the bleeding edge sources, the following pip command can be used:

pip install git+https://github.com/sphinx-contrib/confluencebuilder.git

Tutorial¶

Note

Advanced users of Sphinx can skip this section and view configuration options available to prepare their documentation.

After installing Atlassian Confluence Builder for Sphinx, a Sphinx project can be configured to use supported builders. The following tutorial will provide a series of steps which will:

Enables a user to generate Confluence-compatible markup documentation.
Enables a user to publish to a Confluence instance.

New documentation¶

If a user is starting a new Sphinx-based documentation, the following steps can be used to create a new minimalistic Sphinx configuration or use Sphinx’s quick-start utility. If attempting to use this extension for existing documentation, start configuring for this extension.

Quick-start¶

If opting for the quick-start utility, open a terminal to the location where documentation should be generated (typically, an empty directory) and invoke the following:

sphinx-quickstart
 (or)
python -m sphinx.cmd.quickstart
 (or)
python -m sphinx.quickstart

After completing the quick-start, conf.py can be tweaked as desired. Continue preparing the documentation by configuring for this extension.

Minimalistic¶

For a minimalistic setup, create a new folder for the new documentation and configuration to be used. This is done by first creating a document named index.rst with the following content:

My documentation
================

This is a test document.

Next, create a configuration file conf.py with the following information:

extensions = []

After preparing these files, continue by configuring for this extension as follows.

Configuring to use this extension¶

Enable this extension by registering the extension in the target project’s Sphinx configuration (conf.py):

extensions = [
    'sphinxcontrib.confluencebuilder',
]

Next, include a series of publish-related settings to the configuration file:

confluence_publish = True
confluence_space_key = 'TEST'
confluence_ask_password = True
# (for Confluence Cloud)
confluence_server_url = 'https://example.atlassian.net/wiki/'
confluence_server_user = 'myawesomeuser@example.com'
# (or, for Confluence Server)
confluence_server_url = 'https://intranet-wiki.example.com/'
confluence_server_user = 'myawesomeuser'

Make appropriate changes to the above configuration for the environment being targeted.

Note

The configuration of the space key (confluence_space_key) is case-sensitive. Ensure the value matches the case found on the Confluence instances (typically, uppercase).

Recommended configurations¶

By default, this extension will publish any documents to the root of a configured space. It can be common for most users to want to publish a documentation set as children of an already existing page. To take advantage of this feature, a user will want to define a confluence_parent_page option in their configuration file. For example:

confluence_parent_page = 'MyDocumentation'

When publishing a documentation set, the above configuration will tell this extension to publish all documents under the MyDocumentation page.

For first time users, they may wish to sanity check what content will be published before publishing for the first time to a Confluence instance. A user can perform a dryrun by configuring the confluence_publish_dryrun option in the project’s configuration file. For example:

confluence_publish_dryrun = True

For more information on the above or additional configuration options, see all configuration options.

Building/publishing documentation¶

To process and publish the documentation set, invoke Sphinx with the confluence builder (or a desired builder) to perform building/publishing:

make confluence
 (or)
sphinx-build -b confluence . _build/confluence -E -a
 (or)
python -m sphinx -b confluence . _build/confluence -E -a

Documentation of the project should now be published to the Confluence site.

For users who set the dryrun option above (confluence_publish_dryrun), they may inspect the output of the run to confirm what the publish event will perform. If the desired result is observed, a user can remove the dryrun option and re-invoke the build/publish command to publish onto the configured Confluence instance.

Configuration¶

The following is an example of simple configuration (config.py) for Confluence generation and publishing:

extensions = [
    'sphinxcontrib.confluencebuilder',
]
confluence_publish = True
confluence_space_key = 'TEST'
confluence_parent_page = 'Documentation'
confluence_server_url = 'https://intranet-wiki.example.com/'
confluence_server_user = 'myawesomeuser'
confluence_ask_password = True

All configurations introduced by this extension are listed below. This extension may take advantage of a subset of Sphinx configurations as well when preparing documents.

New in version 1.9: All options provided by this extension may be set from the running environment. For example, if confluence_publish is not explicitly set inside conf.py or provided via Sphinx’s command line, this extension may check the CONFLUENCE_PUBLISH environment option as a fallback. Note that this only applies options provided below and will not work for other configuration options provided by Sphinx or other Sphinx extensions.

Essential configuration ¶

confluence_publish¶

A boolean that decides whether or not to allow publishing. This option must be explicitly set to True if a user wishes to publish content. By default, the value is set to False.

confluence_publish = True

confluence_server_url¶

The URL for the Confluence instance to publish to. The URL should be prefixed with https:// or http:// (depending on the URL target). The target API folder should not be included in the URL (i.e. excluding rest/api/). For a Confluence Cloud instance, an example URL configuration is as follows:

confluence_server_url = 'https://example.atlassian.net/wiki/'

For a Confluence Server instance, an example URL configuration, if the instance’s REST API is https://intranet-wiki.example.com/rest/api/, should be as follows:

confluence_server_url = 'https://intranet-wiki.example.com/'

confluence_space_key¶

New in version 1.7.

Note

Use the key value for the space, not the name of the space. For example, MYAWESOMESPACE instead of My Awesome Space.
The space key is case-sensitive (typically uppercase).

Key of the space in Confluence to be used to publish generated documents to. For example:

confluence_space_key = 'MYAWESOMESPACE'

If attempting to publish to a user’s personal space, the space’s key will typically start with a tilde value followed by the space’s identifier. For example:

confluence_space_key = '~123456789'

confluence_server_user¶

Note

If using a personal access token (PAT), this option does not need to set (see confluence_publish_token).

Note

If trying to use netrc authentication, support is provided by the Requests library [1]. A user can default to using a configured netrc file by not setting a value for confluence_server_user.

The username value used to authenticate with the Confluence instance. If using Confluence Cloud, this value will most likely be the account’s E-mail address. If using Confluence Server, this value will most likely be the username value.

confluence_server_user = 'myawesomeuser@example.com'
 (or)
confluence_server_user = 'myawesomeuser'

confluence_server_pass¶

Caution

It is never recommended to store an API token or raw password into a committed/shared repository holding documentation.

A documentation’s configuration can modified various ways with Python to pull an authentication token for a publishing event such as reading from an environment variable, reading from a local file or acquiring a password from getpass. If desired, this extension provides a method for prompting for a password (see confluence_ask_password).

Note

If attempting to use a personal access token (PAT), use the confluence_publish_token option instead.

The password value used to authenticate with the Confluence instance. If using Confluence Cloud, it is recommended to use an API token for the configured username value (see API tokens):

confluence_server_pass = 'vsUsrSZ6Z4kmrQMapSXBYkJh'

If API tokens are not being used, the plaintext password for the configured username value can be used:

confluence_server_pass = 'myawesomepassword'

confluence_publish_token¶

New in version 1.8.

Caution

It is never recommended to store a personal access tokens (PAT) into a committed/shared repository holding documentation.

A documentation’s configuration can modified various ways with Python to pull an authentication token for a publishing event such as reading from an environment variable, reading from a local file or acquiring a token from getpass.

Note

If attempting to use an API token, use the confluence_server_pass option instead.

The personal access token value used to authenticate with the Confluence instance (see Using Personal Access Tokens):

confluence_publish_token = 'AbCdEfGhIjKlMnOpQrStUvWxY/z1234567890aBc'

Generic configuration ¶

confluence_add_secnumbers¶

New in version 1.2.

Add section numbers to page and section titles if toctree uses the :numbered: option. By default, this is enabled:

confluence_add_secnumbers = True

See also:

confluence_footer_file
confluence_header_data

confluence_header_data¶

New in version 1.9.

Takes an optional dictionary. If this value is set then confluence_header_file is interpreted as a jinja2 template with these values passed in. If this value is not set then confluence_header_file is included verbatim.

See also:

confluence_header_file
confluence_footer_data

confluence_footer_data¶

New in version 1.9.

Takes an optional dictionary. If this value is set then confluence_footer_file is interpreted as a jinja2 template with these values passed in. If this value is not set then confluence_footer_file is included verbatim.

Publishing configuration ¶

confluence_ask_password¶

Warning

User’s running Cygwin/MinGW may need to invoke with winpty to allow this feature to work.

Provides an override for an interactive shell to request publishing documents using an API key or password provided from a shell environment. While a password is typically defined in the option confluence_server_pass (either directly set, fetched from the project’s config.py or passed via an alternative means), select environments may wish to provide a way to accept an authentication token without needing to modify documentation sources or having a visible password value in the interactive session requesting the publish event. By default, this option is disabled with a value of False.

confluence_ask_password = False

A user can request for a password prompt by invoking build event by passing the define through the command line:

sphinx-build [options] -D confluence_ask_password=1 <srcdir> <outdir>

Note that some shell sessions may not be able to pull the password value properly from the user. For example, Cygwin/MinGW may not be able to accept a password unless invoked with winpty.

confluence_ask_user¶

New in version 1.2.

Provides an override for an interactive shell to request publishing documents using a user provided from a shell environment. While a user is typically defined in the option confluence_server_user, select environments may wish to provide a way to accept a username without needing to modify documentation sources. By default, this option is disabled with a value of False.

confluence_ask_user = False

confluence_disable_autogen_title¶

A boolean value to explicitly disable the automatic generation of titles for documents which do not have a title set. When this extension processes a set of documents to publish, a document needs a title value to know which Confluence page to create/update. In the event where a title value cannot be extracted from a document, a title value will be automatically generated for the document. For automatically generated titles, the value will always be prefixed with autogen-. For users who wish to ignore pages which have no title, this option can be set to True. By default, this option is set to False.

confluence_disable_autogen_title = True

See also:

confluence_remove_title
confluence_title_overrides

confluence_cleanup_archive¶

New in version 1.9.

Warning

Publishing individual/subset of documents with this option may lead to unexpected results.

Note

This option cannot be used with confluence_cleanup_purge.

Warning

Only Confluence Cloud identifies support for an archiving API. Attempting to Confluence server with this feature will most likely result in an “Unsupported Confluence API call” error (500).

Attention

Confluence’s archiving API is marked as experimental at the time of writing. This feature may experience issues over time until the API is flagged as stable (if ever).

A boolean value to whether to archive legacy pages detected in a space or parent page. By default, this value is set to False to indicate that no pages will be archived. If this configuration is set to True, detected pages in Confluence that do not match the set of published documents will be automatically archived. If the option confluence_parent_page is set, only pages which are a descendant of the configured parent page can be removed; otherwise, all flagged pages in the configured space could be archived.

confluence_cleanup_archive = False

While this capability is useful for updating a series of pages, it may lead to unexpected results when attempting to publish a single-page update. The archive operation will archive all pages that are not publish in the request. For example, if an original request publishes ten documents and archives excess documents, a following publish attempt with only one of the documents will archive the other nine pages.

See also:

confluence_cleanup_from_root
confluence_cleanup_purge
confluence_cleanup_search_mode
confluence_publish_dryrun

confluence_cleanup_from_root¶

New in version 1.9.

A boolean value to which indicates that any cleanup attempt should be done from the root of a published root_doc page (instead of a configured parent page; i.e. confluence_parent_page). In specific publishing scenarios, a user may wish to publish multiple documentation sets based off a single parent/container page. To prevent any cleanup between multiple documentation sets, this option can be set to True. When generating legacy pages to be removed, this extension will only attempt to populate legacy pages based off the children of the root_doc page. This option requires either confluence_cleanup_archive or confluence_cleanup_purge to be set to True before taking effect. If confluence_publish_root is set, this option is implicitly enabled.

confluence_cleanup_from_root = False

See also:

confluence_cleanup_archive
confluence_cleanup_purge

confluence_cleanup_purge¶

New in version 1.9.

Warning

Publishing individual/subset of documents with this option may lead to unexpected results.

Note

This option cannot be used with confluence_cleanup_archive.

A boolean value to whether or not purge legacy pages detected in a space or parent page. By default, this value is set to False to indicate that no pages will be removed. If this configuration is set to True, detected pages in Confluence that do not match the set of published documents will be automatically removed. If the option confluence_parent_page is set, only pages which are a descendant of the configured parent page can be removed; otherwise, all flagged pages in the configured space could be removed.

confluence_cleanup_purge = False

While this capability is useful for updating a series of pages, it may lead to unexpected results when attempting to publish a single-page update. The purge operation will remove all pages that are not publish in the request. For example, if an original request publishes ten documents and purges excess documents, a following publish attempt with only one of the documents will purge the other nine pages.

See also:

confluence_cleanup_archive
confluence_cleanup_from_root
confluence_cleanup_search_mode
confluence_publish_dryrun

confluence_disable_notifications¶

A boolean value which explicitly disables any page update notifications (i.e. treats page updates from a publish request as minor updates). By default, notifications are enabled with a value of False.

confluence_disable_notifications = True

Note that even if this option is set, there may be some scenarios where a notification will be generated for other users when a page is created or removed, depending on how other users may be watching a space.

See also:

Confluence Spaces and Unique Page Names
confluence_disable_autogen_title
confluence_publish_postfix
confluence_publish_prefix
confluence_remove_title

confluence_timeout¶

Force a timeout (in seconds) for network interaction. The timeout used by this extension is not explicitly configured (i.e. managed by Requests). By default, assume that any network interaction will not timeout. Since the target Confluence instance is most likely to be found on an external server, is it recommended to explicitly configure a timeout value based on the environment being used. For example, to configure a timeout of ten seconds, the following can be used:

confluence_timeout = 10

confluence_watch¶

New in version 1.3.

Indicate whether or not the user publishing content will automatically watch pages for changes. In Confluence, when creating a new page or updating an existing page, the editing user will automatically watch the page. Notifications on automatically published content is typically not relevant to publishers through this extension, especially if the content is volatile. If a publisher wishes to be keep informed on notification for published pages, this option can be set to True. By default, watching is disabled with a value of False.

confluence_watch = False

Advanced publishing configuration ¶

confluence_append_labels¶

New in version 1.3.

Allows a user to decide how to manage labels for an updated page. When a page update contains new labels to set, they can either be stacked on existing labels or replaced. In the event that a publisher wishes to replace any existing labels that are set on published pages, this option can be set to False. By default, labels are always appended with a value of True.

confluence_append_labels = True

See also:

confluence_global_labels
confluence_metadata directive

confluence_asset_force_standalone¶

New in version 1.3.

Provides an override to always publish individual assets (images, downloads, etc.) on each individual document which uses them. This extension will attempt to minimize the amount of publishing of shared assets on multiple documents by only hosting an asset in a single document. For example, if two documents use the same image, the image will be hosted on the root document of a set and each document will reference the attachment on the root page. A user may wish to override this feature. By configuring this option to True, this extension will publish asset files as an attachment for each document which may use the asset. By default, this extension will attempt to host shared assets on a single document with a value of False.

confluence_asset_force_standalone = True

confluence_asset_override¶

Provides an override for asset publishing to allow a user publishing to either force re-publishing assets or disable asset publishing. This extension will attempt to publish assets (images, downloads, etc.) to pages via Confluence’s attachment feature. Attachments are assigned a comment value with a hash value of a published asset. If another publishing event occurs, the hash value is checked before attempting to re-publish an asset. In unique scenarios, are use may wish to override this ability. By configuring this option to True, this extension will always publish asset files (whether or not an attachment with a matching hash exists). By configuring this option to False, no assets will be published by this extension. By default, this automatic asset publishing occurs with a value of None.

confluence_asset_override = None

confluence_ca_cert¶

Provide a CA certificate to use for server certificate authentication. The value for this option can either be a file of a certificate or a path pointing to an OpenSSL-prepared directory. Refer to the Requests SSL Cert Verification documentation (verify) for more information. If server verification is explicitly disabled, this option is ignored. By default, this option is ignored with a value of None.

confluence_ca_cert = 'ca.crt'

See also:

confluence_client_cert_pass
confluence_client_cert
confluence_disable_ssl_validation

confluence_cleanup_search_mode¶

New in version 2.1.

Warning

The direct search mode may not work on Confluence Server/DC instances. For these cases, Confluence may report the following error:

(Not Implemented; 500)

Page children is currently only supported for direct children.

Configures the search mode used for finding descendant pages to be cleaned up (when configured for archiving/purging legacy pages). By default, this extension will search Confluence for known descendants for the root page:

confluence_cleanup_search_mode = 'search'

However, in some cases, the provided list of descendants may be incorrect (due to the Confluence version used, the state of Confluence’s ancestors table caching, etc.). This configuration can be used to tweak how this extension searches for descendants, if a user experiences issues with the default method of searching. Supported modes are as follows:

direct: Query known descendants from a page’s cache.
search (default): Search for descendants using Confluence’s CQL capability.

Users can also postfix -aggressive (e.g. search-aggressive) on a mode to perform a recursive search for descendants ensure all descendants are found. Note that an aggressive search will increase the amount of API calls to a configured Confluence instance. See also:

confluence_cleanup_archive
confluence_cleanup_purge

confluence_client_cert¶

Provide a client certificate to use for two-way TLS/SSL authentication. The value for this option can either be a file (containing a certificate and private key) or as a tuple where both certificate and private keys are explicitly provided. If a private key is protected with a passphrase, a user publishing a documentation set will be prompted for a password (see also confluence_client_cert_pass). By default, this option is ignored with a value of None.

confluence_client_cert = 'cert_and_key.pem'
 (or)
confluence_client_cert = ('client.cert', 'client.key')

See also:

confluence_ca_cert
confluence_client_cert_pass
confluence_disable_ssl_validation

confluence_client_cert_pass¶

Caution

It is never recommended to store a certificate’s passphrase into a committed/shared repository holding documentation.

Provide a passphrase for confluence_client_cert. This prevents a user from being prompted to enter a passphrase for a private key when publishing. If a configured private key is not protected by a passphrase, this value will be ignored. By default, this option is ignored with a value of None.

confluence_client_cert_pass = 'passphrase'

confluence_ca_cert
confluence_client_cert
confluence_disable_ssl_validation

confluence_disable_ssl_validation¶

Warning

It is not recommended to use this option.

A boolean value to explicitly disable verification of server SSL certificates when making a publish request. By default, this option is set to False.

confluence_disable_ssl_validation = False

confluence_ca_cert
confluence_client_cert
confluence_client_cert_pass

confluence_ignore_titlefix_on_index¶

New in version 1.3.

When configured to add a prefix or postfix onto the titles of published documents, a user may not want to have any title modifications on the index page. To prevent modifying an index page’s title, this option can be set to True. By default, this option is set to False.

confluence_ignore_titlefix_on_index = True

See also:

confluence_publish_postfix
confluence_publish_prefix

confluence_proxy¶

REST calls use the Requests library, which will use system-defined proxy configuration; however, a user can override the system-defined proxy by providing a proxy server using this configuration.

confluence_proxy = 'myawesomeproxy:8080'

confluence_publish_allowlist¶

New in version 1.3.

Changed in version 2.0: An empty allow list will no longer publish any documents.

Note

Using this option will disable the confluence_cleanup_archive and confluence_cleanup_purge options.

Defines a list of documents to be published to a Confluence instance. When a user invokes sphinx-build, a user has the ability to process all documents (by default) or specifying individual filenames which use the provide files and detected dependencies. If the Sphinx-detected set of documents to process contains undesired documents to publish, confluence_publish_allowlist can be used to override this. This option accepts either a list of relative path document names (without an extension) or a filename which contains a list of document names.

For example, a user can specify documents in a list to allow for publishing:

confluence_publish_allowlist = [
    'index',
    'foo/bar',
]

Alternatively, a user can specify a filename such as following:

confluence_publish_allowlist = 'allowed-docs.txt'

Which could contain a list of documents to allow:

index
foo/bar

A user can configured an allowed list of documents through the command line:

sphinx-build [options] -D confluence_publish_allowlist=index,foo/bar \
    <srcdir> <outdir> index.rst foo/bar.rst

By default, this option is ignored with a value of None.

Advanced processing configuration ¶

confluence_additional_mime_types¶

New in version 1.3.

Candidate selection for images will only support the internally managed list of MIME types supported by a default Confluence instance. A custom installation or future installations of a Confluence instance may support newer MIME types not explicitly managed by this extension. This configuration provides a user the option to register additional MIME types to consider for image candidates.

confluence_additional_mime_types = [
    'image/tiff',
]

confluence_file_suffix¶

The file name suffix to use for all generated files. By default, all generated files will use the extension .conf.

confluence_file_suffix = '.conf'

See also:

confluence_lang_transform¶

Changed in version 2.1: Support a None return to use a default value.

A function to override the translation of literal block-based directive language values to Confluence supported code block macro language values. The default translation accepts Pygments documented language types to Confluence-supported syntax highlight languages.

def my_language_translation(lang):
    return 'default'

confluence_lang_transform = my_language_translation

In the event that the transform returns a None value, the provided language type will be transform to a default language type for a language as if this transform was not provided.

confluence_latex_macro¶

New in version 1.8.

Note

Confluence does not provide stock support for LaTeX macros.

The name of a LaTeX macro to use when wishing to render LaTeX content on a Confluence instance. Stock Confluence instances do not support LaTeX content by default. However, if an instance has installed a marketplace add-on that supports LaTeX, this option can be used to hint to render LaTeX content (such as mathematical notation) by configuring this option.

confluence_latex_macro = 'macro-name'
 (or)
confluence_latex_macro = {
    'block-macro': 'block-macro-name',
    'inline-macro': 'inline-macro-name',
    'inline-macro-param': 'inline-macro-parameter', # (optional)
}

The name of a LaTeX macro will vary based on which add-on is installed. For a list of known macro names or steps to determine the name of a supported macro, see the macro table/instructions found in the math guide.

If this option is not set, any LaTeX content processed in a document will instead be converted to images using dvipng/dvisvgm (see also sphinx.ext.imgmath for additional information).

See also:

confluence_link_suffix¶

The suffix name to use for generated links to files. By default, all generated links will use the value defined by confluence_file_suffix.

confluence_link_suffix = '.conf'

See also:

Mention roles

confluence_navdocs_transform¶

New in version 1.7.

A function to override the document list used for populating navigational buttons generated from a confluence_prev_next_buttons_location configuration. This can be helpful in advanced publishing cases where a user would like ignore or re-order select pages from navigation, or even reference pages outside of documentation list.

 def my_navdocs_transform(builder, docnames):
     # override and return a new docnames list
     return docnames

confluence_navdocs_transform = my_navdocs_transform

confluence_remove_title¶

A boolean value to whether or not automatically remove the title section from all published pages. In Confluence, page names are already presented at the top. With this option enabled, this reduces having two leading headers with the document’s title. In some cases, a user may wish to not remove titles when custom prefixes or other custom modifications are in play. By default, this option is enabled with a value of True.

confluence_remove_title = True

See also:

confluence_disable_autogen_title
confluence_title_overrides

Other options ¶

suppress_warnings¶

New in version 2.1.

This extension supports suppressing warnings using Sphinx’s suppress_warnings configuration. The following includes additional warning types that may be suppressed:

confluence – All warnings
confluence.unsupported_code_lang – Unsupported code language

Deprecated options ¶

confluence_master_homepage¶: Changed in version 1.6.

This option has been renamed to confluence_root_homepage.

confluence_parent_page_id_check¶

Changed in version 1.9: The confluence_parent_page option now accepts both a page name and identifier.

The page identifier check for confluence_parent_page. By providing an identifier of the parent page, both the parent page’s name and identifier must match before this extension will publish any content to a Confluence instance. This serves as a sanity-check configuration for the cautious.

confluence_parent_page_id_check = 123456

Builders¶

The following outlines the Sphinx builders provided by this extension.

confluence¶

The confluence builder allows a user to process a Sphinx supported documentation set to generate a Confluence supported representation. Individual documents will generate Confluence supported documents, which in turn can be published to a configured Confluence instance:

sphinx-build -b confluence . _build/confluence -E -a

singleconfluence¶

New in version 1.3.

The singleconfluence builder allows a user to process a Sphinx supported documentation set to generate a single document in a Confluence supported representation. The generated document can in turn be published to a configured Confluence instance:

sphinx-build -b singleconfluence . _build/singleconfluence -E -a

Directives¶

The following outlines additional directives supported by this extension.

Directives listed below are only supported when using this extension. For users with documentation that is built with multiple builders, the following can be used to restrict these directives to supported builders by using the :only: directive. For example:

.. only:: builder_confluence or builder_singleconfluence

    .. confluence_metadata::
        :labels: label-test

Common¶

.. confluence_excerpt::¶

New in version 2.0.

The confluence_excerpt directive allows a user to define a Confluence Excerpt Macro to help build snippets of content to be shared for other pages. For example:

.. confluence_excerpt::

    This content is reusable.

This directive supports the following options:

:atlassian-macro-output-type: output type (block, inline)¶

When this option is configured to inline (default), the rendered excerpt macro will be presented inlined with other content in the page (no additional line breaks). The block type can be used to help render an excerpt macro as a block-level element.

.. confluence_excerpt::
    :atlassian-macro-output-type: block

    This content is reusable.

:hidden: flag (boolean)¶

Whether the macro’s content should be rendered on the page that defines it. Valid values are true or false (default).

.. confluence_excerpt::
    :hidden: true

    This content is reusable.

:name: value (string)¶

A name value to apply to the macros “name” field. This can be used to name a specific excerpt on a page, which can be explicitly mapped to with an excerpt-include when attempting to define multiple excerpts on the same page. If only a single excerpt is created, an excerpt-include will implicitly use the first excerpt on a page.

.. confluence_excerpt::
    :name: my-excerpt

    This content is reusable.

.. confluence_excerpt_include:: [ref]¶

New in version 2.0.

The confluence_excerpt_include directive allows a user to define a Confluence Excerpt Include Macro to help include snippets of content provided by excerpt macro definitions. An include macro requires an explicit reference to the page which holds the excerpt content to load. Users can specify an exclamation-prefixed document name, referring to a local Sphinx documentation file to load an excerpt from. For example:

.. confluence_excerpt_include:: !my-excerpt-docname

Users may also specify a known document title name that may be managed outside their Sphinx project set. For example:

.. confluence_excerpt_include:: Custom excerpt

To target a page on a different space, the space name can be prefixed before the document title:

.. confluence_excerpt_include:: MYSPACE:Custom excerpt

This directive supports the following options:

:name: value (string)¶

The explicit name of the excerpt to use for a given page. If no name is provided, the excerpt-include macro will use the first available excerpt on the target page.

.. confluence_excerpt_include:: !my-excerpt-docname
    :name: my-excerpt

:nopanel: flag (boolean)¶

Whether the macro’s content should remove the panel around the excerpted content. Valid values are true or false (default).

.. confluence_excerpt_include:: !my-excerpt-docname
    :nopanel: true

.. confluence_expand::¶

New in version 1.3.

The confluence_expand directive allows a user to define a Confluence Expand Macro to help manage the visibility of content on a page. For example:

.. confluence_expand::

    This content is captured inside the expand macro.

This directive supports the following options:

:title: value (string)¶

A string value to apply to the macros “title” field.

.. confluence_expand::
    :title: View more details...

    This content is captured inside the expand macro.

.. confluence_metadata::¶

New in version 1.3.

The confluence_metadata directive allows a user to define metadata information to be added during a publish event. This directive supports the following options:

:labels: value (space separated strings)¶

A space-separated list of label strings to apply to a page. The following example will result in the labels label-a and label-b being added to the document which defines this directive.

.. confluence_metadata::
    :labels: label-a label-b

See also confluence_global_labels (ref).

.. confluence_newline::¶

New in version 1.7.

The confluence_newline directive supports the injection of a newline in a document where seperation may be desired between inlined elements.

.. confluence_newline::

.. confluence_toc::¶

New in version 1.9.

The confluence_toc directive allows a user to define a Confluence Table of Contents Macro. Users are typically recommended to use reStructuredText’s Table of Contents directive when generating local table of contents; and Confluence’s Table of Contents macro is typically not a replacement of Sphinx’s toctree directive. However, if a user wishes to take advantage of Confluence’s TOC-specific macro capabilities, the following can be used:

.. confluence_toc::

This directive supports the following options:

:absolute-url: flag (boolean)¶

Whether the macro should generate full URLs for TOC entry links. Valid values are true or false (default).

.. confluence_toc::
    :absolute-url: true

:exclude: value (string)¶: Filter heading to exclude entries matching the provided value. The value should support a regular expressions string.

:include: value (string)¶: Filter heading to include entries matching the provided value. The value should support a regular expressions string.

:indent: value (string)¶

The indent to apply for header entries.

.. confluence_toc::
    :indent: 15px

:max-level: count (number)¶

Defines the lowest heading level to include in the table of contents.

.. confluence_toc::
    :max-level: 10

:min-level: count (number)¶

Defines the highest heading level to include in the table of contents.

.. confluence_toc::
    :min-level: 1

:outline: flag (boolean)¶

Whether the macro should include outline numbering for entries. Valid values are true or false (default).

.. confluence_toc::
    :outline: true

:printable: flag (boolean)¶

Whether the macro should render when a user prints a Confluence page. Valid values are true (default) or false.

.. confluence_toc::
    :printable: true

:separator: separator style type of the toc (brackets, braces, parens, <user-defined>)¶

When the type option is configured to flat, this option can configure the separator type applied between header entries. By default, the separator type is set to brackets.

.. confluence_toc::
    :separator: braces

:style: list style type of the toc (default, none, disc, circle, square, decimal, lower-alpha, lower-roman, upper-roman)¶

Configures how the table of contents will be style its list type. By default, the style type is set to default.

.. confluence_toc::
    :style: square

:type: outline type of the toc (flat or list)¶

Configures how the table of contents will be style its structure. Valid values are flat or list (default).

.. confluence_toc::
    :type: flat

Jira¶

The following directives can be used to help include Jira macros into generated Confluence documents.

.. jira:: [jql]¶

New in version 1.2.

The jira directive allows a user to build a Jira macro to be configured with a provided JQL query. For example:

.. jira:: project = "TEST"

This directive supports the following options:

:columns: value (comma separated numbers)¶

A comma-separated list of columns to use when displaying the macro to show in the Jira table.

.. jira:: project = "TEST"
    :columns: key,summary,updated,status,resolution

:count: flag (boolean)¶

Whether the macro should display a table or just the number of issues. Valid values are true or false.

.. jira:: project = "TEST"
    :count: true

:maximum_issues: count (number)¶

The maximum number of issues a jira directive will display. By default, Confluence defaults to 20.

.. jira:: project = "TEST"
    :maximum_issues: 10

:server: instance (string)¶

Indicates a named Jira server provided via confluence_jira_servers (ref). When set, options server-id and server-name cannot be set.

.. jira:: project = "TEST"
    :server: server-1

:server-id: uuid (string)¶

The UUID of the Jira server to link with. When set, the option server-name needs to be set and the option server cannot be set.

.. jira:: project = "TEST"
    :server-id: d005bcc2-ca4e-4065-8ce8-49ff5ac5857d
    :server-name: MyAwesomeJiraServer

:server-name: name (string)¶

The name of the Jira server to link with. When set, the option server-id needs to be set and the option server cannot be set.

.. jira:: project = "TEST"
    :server-id: d005bcc2-ca4e-4065-8ce8-49ff5ac5857d
    :server-name: MyAwesomeJiraServer

.. jira_issue:: [issue-id]¶

New in version 1.2.

The jira_issue directive allows a user to build a Jira macro to be configured with a provided Jira key. For example:

.. jira_issue:: TEST-123

This directive supports the following options:

:server: instance (string)¶

Indicates a named Jira server provided via confluence_jira_servers (ref). When set, options server-id and server-name cannot be set.

.. jira_issue:: TEST-123
    :server: server-1

:server-id: uuid (string)¶

The UUID of the Jira server to link with. When set, the option server-name needs to be set and the option server cannot be set.

.. jira_issue:: TEST-123
    :server-id: d005bcc2-ca4e-4065-8ce8-49ff5ac5857d
    :server-name: MyAwesomeJiraServer

:server-name: name (string)¶

The name of the Jira server to link with. When set, the option server-id needs to be set and the option server cannot be set.

.. jira_issue:: TEST-123
    :server-id: d005bcc2-ca4e-4065-8ce8-49ff5ac5857d
    :server-name: MyAwesomeJiraServer

LaTeX¶

Note

LaTeX support requires dvipng/dvisvgm to be installed on system; however, if a Confluence instance supports a LaTeX macro, the confluence_latex_macro (ref) option can be used instead. For more information, please read Math support.

The following directive can be used to help add LaTeX content into a Confluence page.

.. confluence_latex::¶

New in version 1.8.

The confluence_latex directive allows a user to add LaTeX content into a document. For example:

.. confluence_latex::

    $\mathfrak{H}$ello world!

This directive supports the following options:

:align: "left", "center", or "right" (string)¶

The alignment to apply on the LaTeX content. By default, the value is set to center.

.. confluence_latex::
    :align: left

    $\mathfrak{H}$ello world!

Smart links¶

Note

Smart links will only render when using the v2 editor (see confluence_editor; ref).

.. confluence_doc::¶

New in version 2.1.

The confluence_doc directive allows a user to define a link to a document that is styled with a card appearance. The directive accepts the name of a document in an absolute or relative fashion (in the same manner as Sphinx’s :doc: role). For example:

.. confluence_doc:: my-other-page

This directive supports the following options:

:card: card type (block, embed)¶

When using block, a smart link card is generated for the document link. The card will provide a summary of the target document. When using embed, the contents of the document will rendered on the page.

.. confluence_doc:: my-other-page
    :card: block

:layout: layout type (align-start, align-end, center, wrap-left, wrap-right)¶

Note

This option is only applicable when using an embed card.

Specifies how an embedded card will be laid out on a page. Embedded cards will default to 100% width. Therefore, to take advantage of certain layout capabilities, users should also assign an appropriate width as well.

.. confluence_doc:: my-other-page
    :card: embed
    :layout: align-end
    :width: 20

:width: value (integer)¶

Note

This option is only applicable when using an embed card.

Specifies the width to apply for an embedded card. The width is a value from 0 to 100 (e.g. a value of 80 for 80% of the page).

.. confluence_doc:: my-other-page
    :card: embed
    :width: 50

.. confluence_link::¶

New in version 2.1.

The confluence_link directive allows a user to define a link to a page that is styled with a card appearance. The directive accepts a URL. How Confluence renders the context of a link card will vary based on which link targets Confluence supports. For example:

.. confluence_link:: https://example.com

This directive supports the following options:

:card: card type (block, embed)¶

When using block, a smart link card is generated for the link. The card will provide a summary of the target link. When using embed, the contents of the link will rendered on the page.

.. confluence_link:: https://example.com
    :card: block

:layout: layout type (align-start, align-end, center, wrap-left, wrap-right)¶

Note

This option is only applicable when using an embed card.

Specifies how an embedded card will be laid out on a page. Embedded cards will default to 100% width. Therefore, to take advantage of certain layout capabilities, users should also assign an appropriate width as well.

.. confluence_link:: https://example.com
    :card: embed
    :layout: align-end
    :width: 20

:width: value (integer)¶

Note

This option is only applicable when using an embed card.

Specifies the width to apply for an embedded card. The width is a value from 0 to 100 (e.g. a value of 80 for 80% of the page).

.. confluence_link:: https://example.com
    :card: embed
    :width: 50

Roles¶

The following outlines additional roles supported by this extension.

Emoticon Macro¶

The following role can be used to help include Confluence emoticon macros into generated Confluence documents.

:confluence_emoticon:¶

New in version 1.9.

The confluence_emoticon role allows a user to build inlined emoticon macros. For example:

:confluence_emoticon:`tick`: This is done.

:confluence_emoticon:`cross`: This is incomplete.

Jira¶

The following role can be used to help include Jira macros into generated Confluence documents.

:jira:¶

New in version 1.7.

The jira role allows a user to build an inlined Jira macro to be configured with a provided Jira key. For example:

See :jira:`TEST-123` for more details.

LaTeX¶

Note

LaTeX support requires dvipng/dvisvgm to be installed on system; however, if a Confluence instance supports a LaTeX macro, the confluence_latex_macro (ref) option can be used instead. For more information, please read Math support.

The following role can be used to help include LaTeX content into generated Confluence documents.

:confluence_latex:¶

New in version 1.8.

The confluence_latex role allows a user to build inlined LaTeX content. For example:

This is a :confluence_latex:`$\\mathfrak{t}$est`.

Mentions¶

The following role can be used to help include Confluence mentions into generated Confluence documents.

:confluence_mention:¶

New in version 1.9.

Warning

Confluence Cloud mentions should always use account identifiers; where Confluence Server mentions should use either usernames or user keys. Attempting to use Confluence Cloud account identifiers when publishing to a Confluence server will most likely result in an “Unsupported Confluence API call” error (500).

The confluence_mention role allows a user to build inlined mentions. For Confluence Cloud instances, a mention to a specific user’s account identifier would be defined as follows:

See :confluence_mention:`3c5369:fa8b5c24-17f8-4340-b73e-50d383307c59`.

For Confluence Server instances, a mention to a specific user can either be set to the username value, or a user’s key value:

For more information, contact :confluence_mention:`myuser`.
 (or)
Contact :confluence_mention:`b9aaf35e80441f415c3a3d3c53695d0e` for help.

A user mapping table can also be configured using the confluence_mentions (ref) option.

Smart links¶

Note

Smart links will only render when using the v2 editor (see confluence_editor; ref).

Support for inlined smart links can be created using the following roles.

:confluence_doc:¶

New in version 2.1.

The confluence_doc role allows a user to define an inlined link to a document that is styled with a card appearance. The role accepts the name of a document in an absolute or relative fashion (in the same manner as Sphinx’s :doc: role). For example:

See :confluence_doc:`my-other-page`.

:confluence_link:¶

New in version 2.1.

The confluence_link role allows a user to define an inlined link to a page that is styled with a card appearance. The role accepts a URL. How Confluence renders the context of a link card will vary based on which link targets Confluence supports. For example:

See :confluence_link:`https://example.com`.

Status Macro¶

The following role can be used to help include Confluence status macro into generated Confluence documents.

:confluence_status:¶

New in version 1.9.

The confluence_status role allows a user to build inlined status macros. For example:

:confluence_status:`My Status`

The color of a status macro can be configured to a value supported by Confluence’s status macro. For example, to adjust the status value to a yellow color, the following can be used:

:confluence_status:`WARNING <yellow>`

To tweak the style of a status macro to an outlined variant (if supported by the configured Confluence editor), adjust the color enclosure to square brackets:

:confluence_status:`PASSED [green]`

Strikethrough¶

Note

This role can be used to help a user observe the ability to strikethrough text on a Confluence page; however, this role only applies to Confluence builders. Users attempting to support multiple builders (such as the html builder), are recommended to use a class hint instead. This extension supports an applied strike class on text as an indication that the text should have a strikethrough format. For example:

.. role:: strike
    :class: strike

This is a :strike:`strikeme` example.

The following role can be used to explicitly define strikethrough text into generated Confluence documents.

:confluence_strike:¶

New in version 2.1.

The confluence_strike role allows a user to build inlined text that has been styled with a strikethrough. For example:

:confluence_strike:`My text`

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	Limited support. 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). When the `class` attribute contains `collapse`, the macro will be configured to be collapsed.
deprecated	Supported
download	Supported
glossary	Supported
hlist	Supported
manpage	Supported
production list	Supported
toctree	Supported
versionadded	Supported
versionchanged	Supported

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 have been tested. If a type of reference does not work or yields unexpected results, please report the issue with an example.
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 shows 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 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

https://github.com/sphinx-contrib/confluencebuilder/issues

Tips¶

Confluence spaces and unique page names¶

An important consideration when using this extension is that Confluence has a requirement to having unique page names for a given space. When this extension parses a document’s title value, the title is used as either a creation point or an update point (i.e. if the page name does not exist, it will be created; if the page name does exist, it will be updated).

A user must be cautious when mixing a space with manually prepared content and published content from this extension. Consider the following use case.

A space MYAWESOMESPACE already exists with the following content:

MyHome
About
Tutorials
See Also

A user may desire to publish a series of Sphinx documentation into a “container” page, so the page “Documentation” is made:

MyHome
About
Documentation
Tutorials
See Also

If the Sphinx documentation contains a page named “About”, an unexpected event may occur for new users after publishing for the first time. A user might expect the following to be published:

MyHome
About
Documentation
- About (new)
- Installing (new)
- User Guide (new)
- Other (new)
Tutorials
See Also

However, since Confluence only supports a single “About” page for a space, the original “About” page is updated with new content from the documentation set and is moved as a child of the container page:

MyHome
Documentation
- About (updated and moved)
- Installing (new)
- User Guide (new)
- Other (new)
Tutorials
See Also

Users needing to restrict the extension from possibly mangling manually prepared content can use the confluence_publish_prefix (ref) or confluence_publish_postfix (ref) options.

See also the dry run capability and the title overrides capability.

Setting a publishing timeout¶

By default, this extension does not define any timeouts for a publish event. It is recommended to provide a timeout value based on the environment being used (see confluence_timeout; ref).

Wiping a space¶

Danger

Pages removed from this call cannot be recovered without the help of an administrator for the Confluence space which pages will be removed from.

A command line argument wipe is available for users wishing to remove pages from a configured space. This can be useful for users who need to clear multiple pages which have been pushed through automation or if the Confluence instance does not support automatically deleting page children.

A wipe request can be started using the following:

$ python -m sphinxcontrib.confluencebuilder wipe --danger
...

Are you sure you want to continue? [y/N] y

         URL: https://intranet-wiki.example.com/
       Space: TEST
       Pages: All Pages
 Total pages: 250

Are you sure you want to REMOVE these pages? [y/N] y

Removing pages.... done

If a user wishes to only remove child pages of a configured parent page, the option --parent can be used:

python -m sphinxcontrib.confluencebuilder wipe --danger --parent

Asking for help¶

Having trouble or concerns using this extension? Do not hesitate to bring up an issue:

Atlassian Confluence Builder for Confluence - Issues

https://github.com/sphinx-contrib/confluencebuilder/issues

For issues when using this extension, generating a report and including this content in an issue may be helpful towards finding a solution. To generate a report, run the following command from the documentation directory:

$ python -m sphinxcontrib.confluencebuilder report
...
Confluence builder report has been generated.
Please copy the following text for the GitHub issue:

------------[ cut here ]------------
(system)
...

(configuration)
...

(confluence instance)
 ...
------------[ cut here ]------------

Guides¶

The following contains a series of guides which may help a user using the Confluence Builder extension in a Sphinx-enabled environment.

Collapsed content¶

There are a series of collapsed element capabilities supported by the Confluence builder extension. This guide will cover the available options that can be used.

Expand directive¶

New in version 1.3.

This extension provides a confluence_expand directive to help collapse content. For example:

.. confluence_expand::

    This content is captured inside the expand macro.

This directive will only work when using the Confluence builder. See also the Confluence expand directive.

Class hints¶

New in version 2.1: Support added for containers.

New in version 2.0: Support added for code blocks.

This extension provides support for managing collapsed elements when a collapse class hint is provided. If a container is defined with the style configured, the contents of the directive will be collapsed:

.. container:: collapse

    This paragraph should be collapsed.

When using the code block directive, providing a collapse style hint will also collapse the code block:

.. code-block:: python
    :class: collapse

    import example
    example.method()

sphinx-toolbox’s collapse directive¶

New in version 1.7.

When using the sphinx-toolbox extension, the collapse directive should be able to manage collapsed content. For example:

.. collapse:: Details

    This paragraph should be collapsed.

For more details, please see sphinx-toolbox’s documentation on the collapse directive.

Math support¶

Changed in version 1.8: Support for using Confluence-supported LaTeX macros.

Changed in version 1.7: SVG-generated math images requires the sphinx.ext.imgmath extension to be explicitly registered to work.

Changed in version 1.4: Support both block and inlined math elements.

New in version 1.2: Initial support for math.

Mathematical notation is supported when using the Confluence builder extension. There are some limitations and special cases a user may wish to consider when trying to get the most our of their documentation/environment.

The recommended approach for rendering math in Confluence is using Sphinx’s sphinx.ext.imgmath extension. This extension renders math via LaTeX and uses either dvipng or dvisvgm to create PNG or SVG images which are published to Confluence (which requires installing a LaTeX engine alongside the Sphinx installation, such as a TeX suite/MiKTeX installation).

Math can be defined using the :math: role or the .. math:: directive. For example:

The Pythagorean theorem formula is :math:`a^2 + b^2 = c^2`.

The mass–energy equivalence formula:

.. math::

    E = mc^2

The former case will generate math content in an inlined fashion, where the latter will generate a math block. Math defined in this way is supported on Sphinx’s standard builders with the help of other Sphinx-provided math extensions.

Recommended options for math¶

Ensure the sphinx.ext.imgmath extension is added to the documentation’s extension list:

extensions = [
    'sphinx.ext.imgmath',
    'sphinxcontrib.confluencebuilder',
]

If loading the sphinx.ext.imgmath extension conflicts with other builders, the extension can be optionally included using an approach such as follows (but may require additional changes depending on the environment):

import sys

extensions = [
    'sphinxcontrib.confluencebuilder',
]

if any('confluence' in arg for arg in sys.argv):
    extensions.append('sphinx.ext.imgmath')

The following are the recommended options to use:

imgmath_font_size = 14
imgmath_image_format = 'svg'
imgmath_use_preview = True

This configures the generated font size commonly observed on Confluence instances, hints that images are generated into SVG images (for ideal image scaling) and attempt to process the “depth” of an image to better align content alongside text.

Support for LaTeX macros for math¶

Note

This section outlines how users can take advantage of LaTeX macros enabled on their Confluence instance. The Confluence builder extension only helps forward LaTeX-generated content directly into macros. How a LaTeX macro decides to handle/render LaTeX content is up to the provider supporting the macro.

Note

Not all LaTeX macros support block and inline macros (normally, just the former).

Note

Confluence builder will attempt to support numbered equations by adding a floating label alongside a rendered math block. The variety of LaTeX macros which exist and limitations in how LaTeX macros are structured in a page may prevent the ability to perfectly align these labels alongside the rendered math content.

A stock Confluence instance does not provided LaTeX support. This is the main reason why the Confluence builder extension promotes the use of sphinx.ext.imgmath. However, if a user’s Confluence instance supports a marketplace add-on which provides LaTeX macro support, math content can instead be injected into these macros instead.

To use a LaTeX macro, the confluence_latex_macro (ref) configuration option can be used. This option accepts either the name of a macro to use or a dictionary of macro options to consider (the dictionary is for more complex configurations such as when attempting to support block-specific and inlined-specific macros). For example, to specify the macro to use for any LaTeX content, the following can be used:

confluence_latex_macro = 'macro-name'

If an environment supports a macro which supports block and inlined content in different macros, the following can be used:

confluence_latex_macro = {
    'block-macro': 'block-macro-name',
    'inline-macro': 'inline-macro-name',
    'inline-macro-param': 'inline-macro-parameter', # (optional)
}

LaTeX macro names¶

What macro names to use will vary based off which macro types are installed (if any). Please see the following table for reported macro names:

Marketplace Application	Configuration
Content Formatting Macros for Confluence	confluence_latex_macro = 'latex-formatting'
LaTeX for Confluence	confluence_latex_macro = 'orah-latex'
LaTeX Math	confluence_latex_macro = { 'block-macro': 'mathblock', 'inline-macro': 'mathinline', 'inline-macro-param': 'body', }

If a Confluence environment supports a different macro type, a user can determine the name of the macro by:

Creating a new page on the Confluence instance
Adding a LaTeX macro on the page and saving
Selecting the page’s option menu and selecting “View Storage format”
Look for the corresponding macro name inside an ac:name attribute (in this case, the macro’s name is my-latex-macro):
```
<ac:structured-macro ac:name="my-latex-macro" ...>
  ...
</ac:structured-macro>
```

Publishing with CI¶

Note

If running in a tox/virtualenv setup, ensure any environment variables used are configured to be passed through to the virtual environment.

Tip

As of v1.9, this extension can automatically accept configuration options from the environment that have not been explicitly set in conf.py or provided by the command line. For example, to configure for authentication using a personal access token using the environment, do not add confluence_publish_token into conf.py and ensure the CONFLUENCE_PUBLISH_TOKEN environment variable is set.

For users performing automatic publishing through a CI system, they may wish to authenticate their publish event with a secret key. A common approach to applying a secret key is through an environment variable. For example, if authenticating with an API key (see API tokens), the following can be used:

import os

...

confluence_server_user = 'api-key-uid'
confluence_server_pass = os.getenv('SECRET_KEY')

Or, if using a personal access token (see Using Personal Access Tokens), the following can be used:

import os

...

confluence_publish_token = os.getenv('SECRET_KEY')

Both examples above will read an environment variable SECRET_KEY prepared in a CI environment to be used for authentication.

See confluence_server_pass (ref) and confluence_publish_token (ref) for more information.

Advanced¶

Publishing permissions¶

An account used for authentication will have the best experience with the following permissions when attempting to publish to a configured space:

Space – View
Page – Add, Delete
Attachments – Add, Delete

Delete permissions are only required for environments using the confluence_cleanup_purge (ref) capabilitity.

For environments using an OAuth connector, the following scopes are required:

delete:content:confluence
read:content-details:confluence
write:attachment:confluence
write:content:confluence
write:watcher:confluence

Changelog¶

2.1.1 (2023-05-19)¶

Ensure source distribution includes the LICENSE document
Fixed issue where v2 editor may fail with object has no attribute error

2.1.0 (2023-05-15)¶

Allow users to configure legacy page search mode for cleanup
Fixed anchor page links with v2 editor
Fixed document processing issues with Sphinx 6.1.x
Improve rendering when using sphinxcontrib-needs extension
Introduce Confluence Smart link directives/roles
Introduce the Confluence strike role
Perform an attachment re-upload attempt on an unexpected Confluence 503 error
Provide fallback styling for code languages with a similar style
Support Codeberg helper for source links
Support confluence_full_width with v1 editor
Support default-fallback when using confluence_lang_transform
Support deployment with Python 3.12
Support publishing only pages with content changes
Support suppressing extension warnings using Sphinx’s suppress_warnings
Support the ability to configure where orphan pages are stored
Support the ability to not publish orphan pages

2.0.0 (2023-01-02)¶

Fixed issue publishing orphan pages when a publish root is configured
Fixed issue where captioned code blocks may not be numbered with numfig
Fixed issue where captioned tables were not be numbered with numfig
Hierarchy mode is now enabled by default
Improve look of quote-like directives
Introduce the Confluence excerpt (macro) directives
Support Confluence Cloud’s “Fabric” (v2) editor
Support collapsible code blocks
Support for Python 2.7 has been dropped
Support for confluence_max_doc_depth has been dropped
Support no publishing with an empty confluence_publish_allowlist

1.9.0 (2022-08-21)¶

(note) Final release supporting Python 2.7
Allow confluence_ca_cert to accept a CA-bundle path
Default publish Intersphinx databases to root documents
Fixed issue where code blocks may not properly render captions
Fixed issue where dry-runs may fail with a non-existent root page
Fixed issue where external references with ampersands would fail to publish
Fixed issue where labels are missing on first-publish on Confluence server
Fixed issue where title length limits were not properly enforced
Improve support for loading local windows CA/root certificates for requests
Introduce the Confluence emoticon (macro) role
Introduce the Confluence status (macro) role
Introduce the Confluence toc (macro) directive
Introduce the Confluence user mention (macro) role
Relax domain restrictions for Intersphinx generation
Support confluence_parent_page to accept a page identifier
Support archiving legacy pages (alternative to purging)
Support configuring configuration options from environment
Support document-specific reproducible hash injection in a postfix
Support jinja2 templating on header/footer templates
Support the ability to disable injecting rest/api in API endpoint url

1.8.0 (2022-03-27)¶

(note) confluence_max_doc_depth support is deprecated (reminder)
(note) (advanced mode) Macro disabling is deprecated
Add configuration for personal access tokens (to avoid header entry changes)
Fixed issue where Confluence cloud did not update homepage on a personal space
Fixed issue where inline internal targets would create an empty link label
Fixed issue where Jira directives/role could not be substituted
Improve formatting when processing autodoc content (containers)
Improve support when using the sphinx-diagrams extension
Improve table-alignment for markdown
Introduce the latex directive/role
removed informational macro styling on figures
Support rate limiting for publish requests
Support setting the comment field in page update events
Support users to render math through available marketplace latex macros

1.7.1 (2021-11-30)¶

Fixed regression where publish-root/dryrun modes would fail with an exception

1.7.0 (2021-11-21)¶

(note) confluence_max_doc_depth support is deprecated (reminder)
confluence_space_name renamed to confluence_space_key
Brackets will be wrapped around bottom footnote entries
Fixed issue where links to numbered section would not work
Fixed issue where publishing could fail without a proxy set for older requests
Fixed issue where report/wipe commands would fail in Python 2.7
Fixed regression in timeout option
Improve dry-run reflecting new attachments to be published
Improve indentations for line-block content
Improve support for attached SVG images with length/scaling modifiers
Improve support for non-pixel length units for images
Improve support for SVG images without an XML declaration
Improve support when publishing page updates converted to a new editor
Improve support when using the sphinx-gallery extension
Improve support when using the sphinx_toolbox extension
Improve support when using the sphinxcontrib-mermaid extension
Improve support when using the sphinxcontrib-needs extension
Improve support when using the sphinxcontrib-youtube extension
Improve user feedback on ancestor page update failures (500 errors)
Improved support for dealing with unreconciled page detections
Introduce the Jira role
Introduce the newline directive
Introduce the page generation notice option (notice for top of documents)
Introduce the source link option (e.g. “Edit Source” link)
Prevent issues with extension directives causing errors with other builders
Provide a configuration hook to override requests session information
Remove borders on footnote tables
Support domain indices generation/processing
Support for leaving resolved toctrees for singleconfluence
Support genindex generation/processing
Support search generation
Support strikethrough through strike role
Support the consideration of confluence_parent_page for wipe requests

1.6.0 (2021-09-26)¶

(note) confluence_max_doc_depth support is deprecated
confluence_master_homepage renamed to confluence_root_homepage
confluence_purge_from_master renamed to confluence_purge_from_root
Always publish without XSRF checks (minimize Confluence instance logging)
Always strip control characters from content
Ensure publish events use legacy editor
Fixed issue where sphinx.ext.imgmath was forced for non-Confluence builds
Fixed issue where rubrics were built as headers and not titled paragraphs
Handle extensions providing Unicode attributes (e.g. sphinxcontrib.drawio)
Improve formatting when processing markdown content
Prevent exceptions where third-party extensions provide invalid image uris
Support rendering explicit newline entries

1.5.0 (2021-05-25)¶

Fixed issue where this extension conflicts with docutils’s translator attribs
Fixed issue with :doc:<> references when using singlebuilder
Fixed issue with alignment changes in newer Sphinx
Fixed issue with caption/title changes in newer docutils/Sphinx
Fixed issue with singlebuilder processing assets
Fixed issue with table width hints using pixels instead of percentages
Improvements for getpass handling in msystem-environments
Support an explicit root page publishing option
Support custom headers for REST calls

1.4.0 (2021-01-17)¶

Fixed issue where a meta node directive would fail the writer stage
Fixed issue where intersphinx would fail in Python 2.7
Fixed issue where not all math directive content would be accepted
Fixed/improved handling of configuration options from command line
Support for math visual depth adjustments (line alignment)
Support for numerical figures and references to these figures
Support late image/download processing (for third-party extensions)

1.3.0 (2020-12-31)¶

(note) Support for Sphinx v1.[6-7] has been dropped
(note) Support for XML-RPC has been dropped
Conflicting titles will be automatically adjusted to prevent publishing issues
Enable page-specific title overrides via confluence_title_overrides
Ensure configured title postfix is not trimmed in long titles
Extend language mappings for supported storage format language types
Fixed a series of scenarios where titles/missing images will fail a build
Fixed indentation to consistent offset for newer Confluence instances
Fixed issue when building heading which reference another document
Fixed issue when processing a download role with a url
Fixed issue where an anchor target may not generate a proper link
Fixed issue where ask options would fail in Python 2.7
Fixed issue where ask options would prompt when not publishing
Fixed issue where autosummary registration may fail
Fixed issue where default alignment did not apply to a figure’s legend
Fixed issue where empty pages could not be published
Fixed issue where links to headers which contain a link would fail
Fixed issue where literal-marked includes would fail to publish
Fixed issue where registering this extension caused issues with other builders
Fixed issue where todo entries would render when disabled in configuration
Fixed issue with previous-next links not generated for nested pages
Improved built references by including title (alt) data if set
Improved code macros rendering a title value when a caption is set
Improved emphasis handling for autodocs content
Improved figure/section numbering
Improved handling unknown code languages to none-styled (instead of Python)
Improved previous-next button visualization
Improved publishing when dealing with changing page title casing
Introduce the expand directive
Introduce the report command line feature
Introduce the wipe command line feature
Promote confluence_storage over confluence for raw type
Support :stub-columns: option in a list-table directive
Support disabling titlefix on an index page
Support for assigning Confluence labels for pages
Support for both allow and deny lists for published documents
Support for centered directive
Support for graphviz extension
Support for hlist directive
Support for inheritance-diagram extension
Support image candidate detection of extra image types for custom instances
Support publish dry runs
Support single-page builder
Support the :backlinks: option for contents directive
Support the generation of an inventory file (for intersphinx)
Support users overriding default alignment
Support users to force standalone hosting of shared assets
Support width hints for tables

1.2.0 (2020-01-03)¶

(note) Sphinx v1.[6-7] support for this extension is deprecated
(note) XML-RPC support for this extension is deprecated
Fixed issue when using hierarchy on Sphinx 2.1+ (new citations domain)
Fixed issue with document names with path separators for windows users
Fixed issue with multi-line description signatures (e.g. C++ autodocs)
Fixed issue with processing hidden toctrees
Fixed issue with Unicode paths with confluence_publish_subset and Python 2.7
Improved formatting for option list arguments
Improved handling and feedback when configured with incorrect publish instance
Improved name management for published assets
Improved reference linking for Sphinx domains capability (meth, attr, etc.)
Introduce a series of Jira directives
Support firstline parameter in the code block macro
Support base admonition directive
Support Confluence 7 series newline management
Support default alignment in Sphinx 2.1+
Support document postfixes
Support for generated image assets (asterisk marked)
Support passthrough authentication handlers for REST calls
Support previous/next navigation
Support prompting for publish username
Support sphinx.ext.autosummary extension
Support sphinx.ext.todo extension
Support the math directive
Support toctree’s numbered option
Support users injecting cookie data (for authentication) into REST calls

1.1.0 (2019-03-16)¶

Repackaged release (see sphinx-contrib/confluencebuilder#192)

1.0.0 (2019-03-14)¶

All Confluence-based macros can be restricted by the user
Block quotes with attribution are styled with Confluence quotes
Citations/footnotes now have back references
Enumerated lists now support various styling types
Fixed issue with enumerated lists breaking build on older Sphinx versions
Fixed issue with relative-provided header/footer assets
Fixed issues where table-of-contents may generate broken links
Improve support with interaction with other extensions
Improved paragraph indentation
Initial autodoc support
Nested tables and spanning cells are now supported
Provide option for a caller to request a password for publishing documents
Storage format support (two-pass publishing no longer needed)
Support for sass/yaml language types
Support parsed literal content
Support publishing subset of documents
Support the download directive
Support the image/figure directives
Support the manpage role

0.9.0 (2018-06-02)¶

Fixed a series of content escaping issues
Fixed an issue when purging content would remove just-published pages
Fixed detailed configuration errors from being hidden
Improve proxy support for XML-RPC on various Python versions
Improve support for various Confluence URL configurations
Improve support in handling literal block languages
Support automatic title generation for documents (if missing)
Support :linenothreshold: option for highlight directive
Support maximum page depth (nesting documents)
Support the raw directive
Support two-way SSL connections

0.8.0 (2017-12-05)¶

Fix case where first-publish with confluence_master_homepage fails to configure the space’s homepage
Support page hierarchy
Improve PyPI cover notes

0.7.0 (2017-11-30)¶

Cap headers/sections to six levels for improved visualization
Fixed REST publishing for encoding issues and Python 3.x (< 3.6) issues
Improve markup for:
- Body element lists
- Citations
- Definitions
- Footnotes
- Inline literals
- Literal block (code)
- Rubric
- Seealso
- Table
- Versionmodified
Re-work generated document references/targets (reference to section names)
Sanitize output to prevent Confluence errors for certain characters
Support indentations markup
Support master_doc option to configure space’s homepage
Support removing document titles from page outputs
Support silent page updates

0.6.0 (2017-04-23)¶

Cleanup module’s structure, versions and other minor files
Drop confluence PyPI package (embedded XML-RPC support added)
Improve hyperlink and cross-referencing arbitrary locations/documents support
Improve proxy support
Re-support Python 3.x series
Support anonymous publishing
Support REST API

0.5.0 (2017-03-31)¶

(note) Known issues with Python 3.3, 3.4, 3.5 or 3.6 (see sphinx-contrib/confluencebuilder#10)
Header/footer support
Purging support
Use macros for admonitions

0.4.0 (2017-02-21)¶

Move from Confluence PyPI package to a confluence PyPI package (required for publishing to PyPI; see pycontribs/confluence)

0.3.0 (2017-01-22)¶

Adding Travis CI, tox and initial unit testing
Module now depends on future
Providing initial support for Python 3

0.2.0 (2016-07-13)¶

Moved configuration to the Sphinx config

0.1.1 (2016-07-12)¶

Added table support
Fixed internal links

0.1.0 (2016-07-12)¶

Added lists, bullets, formatted text
Added headings and titles

Option	Description
`owner` (required)	The owner (group or user) of a project.
`repo` (required)	The name of the repository.
`container`	The folder inside the repository which is holding the documentation. This will vary per project, for example, this may be `Documentation/` or `doc/`. If the documentation resides in the root of the repository, this option can be omitted or set to an empty string.
`version` (required)	The version of the sources to list. This is typically set to either a branch (e.g. `main`) or tag value. For Codeberg, also include the version type. For example, `branch/main` or `tag/1.0`.
`view`	The view mode to configure. By default, this value is set to `blob` for GitHub/GitLab and `view` for Bitbucket. GitHub/GitLab users may wish to change this to `edit` to create a link directly to the editing view for a specific document.
`host`	The hostname value to override. This option is useful for instances where a custom domain may be configured for an organization.
`protocol`	The protocol value to override (defaults to `https`).