Documentation contents¶
Installing¶
Atlassian Confluence Builder for Sphinx 1.7.0 depends on:
Python 2.7 or 3.6+
Requests 2.14.0 or later
Sphinx 1.8 or 3.5+
Confluence Cloud or Server 7.2+
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, following provides a series of steps to assist in preparing a new environment to use this package. For users wishing to use virtualenv, please consult 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
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:
# -*- coding: utf-8 -*-
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.
By default, all documents published to a Confluence instance will be stored
either in the root of the space or a configured parent space (as mentioned
above). For larger documentation sets which include multiple nested documents,
it may be desired to have individual documents published as children of other
published documents. Configuring the confluence_page_hierarchy
option will
allow a user to enable hierarchy support. For example:
confluence_page_hierarchy = True
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
confluence_page_hierarchy = 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.
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 toFalse
.confluence_publish = True
- confluence_server_url¶
The URL for the Confluence instance to publish to. The URL should be prefixed with
https://
orhttp://
(depending on the URL target). The target API folder should not be included in the URL (i.e. excludingrest/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 ofMy 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¶
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 (seeconfluence_ask_password
).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 plain password for the configured username value can be used:
confluence_server_pass = 'myawesomepassword'
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_publish_prefix
.
- confluence_default_alignment¶
New in version 1.3.
Explicitly set which alignment type to use when a default alignment value is detected. As of Sphinx 2.0+, the default alignment is set to
center
. Legacy versions of Sphinx had a default alignment ofleft
. By default, this extension will use a Sphinx-defined default alignment unless explicitly set by this configuration value. Accepted values areleft
,center
orright
.confluence_default_alignment = 'left'
- confluence_domain_indices¶
New in version 1.7.
A boolean or list value to configure whether or not generate domain-specific indices. If configured to a value of
True
, all domain-specific indices generated when processing a documentation set will have a Confluence document created. If configured with a list of index names, any matching domain-index with a matching name will have a Confluence document created. By default, domain-specific indices are disabled with a value ofFalse
.confluence_domain_indices = True (or) confluence_domain_indices = [ 'py-modindex', ]
- confluence_header_file¶
The name of the file to use header data. If provided, the raw contents found inside the header file will be added to the start of all generated documents. The file path provided should be relative to the build environment’s source directory. For example:
confluence_header_file = 'assets/header.tpl'
See also
confluence_footer_file
.
The name of the file to use footer data. If provided, the raw contents found inside the footer file will be added at the end of all generated documents. The file path provided should be relative to the build environment’s source directory. For example:
confluence_footer_file = 'assets/footer.tpl'
See also
confluence_header_file
.
- confluence_include_search¶
New in version 1.7.
A boolean value to configure whether or not generate a search page. If configured to a value of
True
, a search page will be created with a search macro configured to search on the configured space. If asearch
document is registered in a documentation’s toctree, a search page will be generated and will replace the contents of the providedsearch
page. To avoid the implicit enablement of this feature, the generation of a search page can be explicitly disabled by setting this value toFalse
. By default, search page generation is automatically managed with a value ofNone
.confluence_include_search = True
- confluence_max_doc_depth¶
Important
This feature is deprecated. If there is a desire to generate a single document page instead, consider using the
singleconfluence
builder instead.A positive integer value, if provided, to indicate the maximum depth permitted for a nested child page before its contents is inlined with a parent. The root of all pages is typically the configured root_doc. The root page is considered to be at a depth of zero. By default, the maximum document depth is disabled with a value of
None
.confluence_max_doc_depth = 2
- confluence_page_generation_notice¶
New in version 1.7.
A boolean value to whether or not to generate a message at the top of each document that the page has been automatically generated. By default, this notice is disabled with a value of
False
.confluence_page_generation_notice = True
- confluence_page_hierarchy¶
A boolean value to whether or not nest pages in a hierarchical ordered. The root of all pages is typically the configured root_doc. If a root_doc instance contains a toctree, listed documents will become child pages of the root_doc. This cycle continues for child pages with their own toctree markups. By default, hierarchy mode is disabled with a value of
False
.confluence_page_hierarchy = True
Note that even if hierarchy mode is enabled, the configured root_doc page and other published pages that are not defined in the complete toctree, these documents will still be published and uploaded to either the configured
confluence_parent_page
or in the root of the space.Important
This feature will default to
True
in a v2.0 release. Users who do not want to use hierarchy mode should explicitly configure this toFalse
in their configurations.
- confluence_prev_next_buttons_location¶
New in version 1.2.
A string value to where to include previous/next buttons (if any) based on the detected order of documents to be included in processing. Values accepted are either
bottom
,both
,top
orNone
. By default, no previous/next links are generated with a value ofNone
.confluence_prev_next_buttons_location = 'top'
- confluence_secnumber_suffix¶
New in version 1.2.
The suffix to put after section numbers, before section name.
confluence_secnumber_suffix = '. '
See also
confluence_add_secnumbers
.
- confluence_use_index¶
New in version 1.7.
A boolean value to configure whether or not generate an index page. If configured to a value of
True
, an index page will be created. If agenindex
document is registered in a documentation’s toctree, index content will be generated and will replace the contents of the providedgenindex
page. To avoid the implicit enablement of this feature, the generation of an index page can be explicitly disabled by setting this value toFalse
. By default, index generation is automatically managed with a value ofNone
.confluence_use_index = True
- singleconfluence_toctree¶
New in version 1.7.
A boolean value to configure whether or not TOC trees will remain in place when building with a
singleconfluence
builder. By default, this option is disabled with a value ofFalse
.singleconfluence_toctree = True
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’sconfig.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 ofFalse
.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 ofFalse
.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 toTrue
. By default, this option is set toFalse
.confluence_disable_autogen_title = True
See also:
- 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_watch
.
- confluence_global_labels¶
New in version 1.3.
Defines a list of labels to apply to each document being published. When a publish event either adds a new page or updates an existing page, the labels defined in this option will be added/set on the page. For example:
confluence_global_labels = [ 'label-a', 'label-b', ]
For per-document labels, please consult the
confluence_metadata
directive. See alsoconfluence_append_labels
.
- confluence_root_homepage¶
New in version 1.6.
A boolean value to whether or not force the configured space’s homepage to be set to the page defined by the Sphinx configuration’s root_doc. By default, the root_doc configuration is ignored with a value of
False
.confluence_root_homepage = False
- confluence_parent_page¶
Note
This option cannot be used with
confluence_publish_root
.The root page found inside the configured space (
confluence_space_key
) where published pages will be a descendant of. The parent page value is used to match with the title of an existing page. If this option is not provided, new pages will be published to the root of the configured space. If the parent page cannot be found, the publish attempt will stop with an error message. For example, the following will publish documentation under theMyAwesomeDocs
page:confluence_parent_page = 'MyAwesomeDocs'
If a parent page is not set, consider using the
confluence_root_homepage
option as well. Note that the page’s name can be case-sensitive in most (if not all) versions of Confluence.See also
confluence_publish_root
.
- confluence_publish_postfix¶
New in version 1.2.
If set, a postfix value is added to the title of all published documents. In Confluence, page names need to be unique for a space. A postfix can be set to either:
Add a unique naming schema to generated/published documents in a space which has manually created pages; or,
Allow multiple published sets of documentation, each with their own postfix value.
An example publish postfix is as follows:
confluence_publish_postfix = '-postfix'
By default, no postfix is used. See also:
- confluence_publish_prefix¶
If set, a prefix value is added to the title of all published documents. In Confluence, page names need to be unique for a space. A prefix can be set to either:
Add a unique naming schema to generated/published documents in a space which has manually created pages; or,
Allow multiple published sets of documentation, each with their own prefix value.
An example publish prefix is as follows:
confluence_publish_prefix = 'prefix-'
By default, no prefix is used. See also:
- confluence_publish_root¶
New in version 1.5.
Note
This option cannot be used with
confluence_parent_page
.The page identifier to publish the root document to. The root identifier value is used to find an existing page on the configured Confluence instance. When found, the root document of the documentation set being published will replace the content of the page found on the Confluence instance. If the root page cannot be found, the publish attempt will stop with an error message.
confluence_publish_root = 123456
See also
confluence_parent_page
.
- confluence_purge¶
Warning
Publishing individual/subset of documents with this option may lead to unexpected results.
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 toTrue
, detected pages in Confluence that do not match the set of published documents will be automatically removed. If the optionconfluence_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_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_purge_from_root¶
New in version 1.6.
A boolean value to which indicates that any purging 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 purging between multiple documentation sets, this option can be set toTrue
. 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 requiresconfluence_purge
to be set toTrue
before taking effect. Ifconfluence_publish_root
is set, this option is implicitly enabled.confluence_purge_from_root = False
See also
confluence_purge
.
- confluence_sourcelink¶
New in version 1.7.
Provides options to include a link to the documentation’s sources at the top of each page. This can either be a generic URL or customized to link to individual documents in a repository.
An example of a simple link is as follows:
confluence_sourcelink = { 'url': 'https//www.example.com/', }
Templates for popular hosting services are available. Instead of defining a
url
option, thetype
option can instead be set to one of the following types:bitbucket
github
gitlab
Options to set for these types are as follows:
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/
ordoc/
. 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.view
The view mode to configure. By default, this value is set to
blob
for GitHub/GitLab andview
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
).For example, a project hosted on GitHub can use the following:
confluence_sourcelink = { 'type': 'github', 'owner': 'sphinx-contrib', 'repo': 'confluencebuilder', 'container': 'doc/', 'version': 'master', 'view': 'edit', }
For unique environments, the source URL can be customized through the
url
option. This option is treated as a format string which can be populated based on the configuration and individual documents being processed. An example is as follows:confluence_sourcelink = { 'url': 'https://git.example.com/mydocs/{page}{suffix}', }
This configures a base URL, where
page
andsuffix
will be generated automatically. Any option provided in theconfluence_sourcelink
dictionary will be forwarded to the format option. For example:confluence_sourcelink = { 'base': 'https://git.example.com/mydocs', 'url': '{base}/{version}/{page}{suffix}', 'version': 'main', }
The
text
option can be used to override the name of the link observed at the top of the page:confluence_sourcelink = { ... 'text': 'Edit Source', }
- confluence_title_overrides¶
New in version 1.3.
Allows a user to override the title value for a specific document. When documents are parsed for title values, the first title element’s content will be used as the publish page’s title. Select documents may not include a title and are ignored; or, documents may conflict with each other but there is a desire to keep them the same name in reStructuredText form. With
confluence_title_overrides
, a user can define a dictionary which will map a given docname to a title value instead of the title element (if any) found in the respective document. By default, documents will give assigned titles values based off the first detected title element with a value ofNone
.confluence_title_overrides = { 'index': 'Index Override', }
See also:
- 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 ofFalse
.confluence_watch = False
See also
confluence_disable_notifications
.
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 ofTrue
.confluence_append_labels = True
See also:
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 ofFalse
.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 toFalse
, no assets will be published by this extension. By default, this automatic asset publishing occurs with a value ofNone
.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 ofNone
.confluence_ca_cert = 'ca.crt'
See also:
- 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 ofNone
.confluence_client_cert = 'cert_and_key.pem' (or) confluence_client_cert = ('client.cert', 'client.key')
See also:
- 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 ofNone
.confluence_client_cert_pass = 'passphrase'
- 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_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 toFalse
.confluence_ignore_titlefix_on_index = True
See also:
- confluence_parent_page_id_check¶
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
See also
confluence_parent_page
.
- 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.
Note
Using this option will disable the
confluence_purge
option.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
.See also
confluence_publish_denylist
.
- confluence_publish_denylist¶
New in version 1.3.
Note
Using this option will disable the
confluence_purge
option.Defines a list of documents to not 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 contain undesired documents to publish,
confluence_publish_denylist
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 deny for publishing:
confluence_publish_denylist = [ 'index', 'foo/bar', ]
Alternatively, a user can specify a filename such as following:
confluence_publish_denylist = 'denied-docs.txt'
Which could contain a list of documents to allow:
index foo/bar
A user can configured a denied list of documents through the command line:
sphinx-build [options] -D confluence_publish_denylist=index,foo/bar \ <srcdir> <outdir> index.rst foo/bar.rst
By default, this option is ignored with a value of
None
.See also
confluence_publish_allowlist
.
- confluence_publish_dryrun¶
New in version 1.3.
When a user wishes to start managing a new document set for publishing, there maybe concerns about conflicts with existing content. When the dry run feature is enabled to
True
, a publish event will not edit or remove any existing content. Instead, the extension will inform the user which pages will be created, whether or not pages will be moved and whether or not pages/attachments will be removed. By default, the dry run feature is disabled with a value ofFalse
.confluence_publish_dryrun = True
See also Confluence Spaces and Unique Page Names.
- confluence_publish_headers¶
New in version 1.5.
A dictionary value which allows a user to pass key-value header information. This is useful for users who need to interact with a Confluence instance which expects (in a reverse proxy or the instance itself) specific header information to be set. By default, no custom header entries are added with a value of
None
.confluence_publish_headers = { 'CUSTOM_HEADER': '<some-value>', }
- confluence_publish_onlynew¶
New in version 1.3.
A publish event will from this extension will typically upload new pages or update existing pages on future attempts. In select cases, a user may not wish to modify existing pages and only permit adding new content to a Confluence space. To achieve this, a user can enable an “only-new” flag which prevents the modification of existing content. This includes the restriction of updating existing pages/attachments as well as deleting content. By default, the only-new feature is disabled with a value of
False
.confluence_publish_onlynew = True
- confluence_request_session_override¶
New in version 1.7.
A hook to manipulate a Requests session prepared by this extension. Allows users who wish to perform advanced configuration of a session for features which may not be supported by this extension.
def my_request_session_override(session): session.trust_env = False confluence_request_session_override = my_request_session_override
- confluence_server_auth¶
An authentication handler which can be directly provided to a REST API request. REST calls in this extension use the Requests library, which provide various methods for a client to perform authentication. While this extension provides simple authentication support (via
confluence_server_user
andconfluence_server_pass
), a publisher may need to configure an advanced authentication handler to support a target Confluence instance.Note that this extension does not define custom authentication handlers. This configuration is a passthrough option only. For more details on various ways to use authentication handlers, please consult Requests – Authentication. By default, no custom authentication handler is provided to generated REST API requests. An example OAuth 1 is as follows:
from requests_oauthlib import OAuth1 ... confluence_server_auth = OAuth1(client_key, client_secret=client_secret, resource_owner_key=resource_owner_key, resource_owner_secret=resource_owner_secret)
- confluence_server_cookies¶
New in version 1.2.
A dictionary value which allows a user to pass key-value cookie information for authentication purposes. This is useful for users who need to authenticate with a single sign-on (SSO) provider to access a target Confluence instance. By default, no cookies are set with a value of
None
.confluence_server_cookies = { 'SESSION_ID': '<session id string>', 'U_ID': '<username>', }
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_file_transform
.
- confluence_file_transform¶
A function to override the translation of a document name to a filename. The provided function is used to perform translations for both Sphinx’s get_outdated_docs and write_doc methods. The default translation will be the combination of “
docname
+confluence_file_suffix
”.
- confluence_jira_servers¶
New in version 1.2.
Provides a dictionary of named Jira servers to reference when using the
jira
orjira_issue
directives. In a typical Confluence environment which is linked with a Jira instance, users do not need to take advantage of this configuration – Confluence should automatically be able to link to respectively Jira issues or map Jira query languages with a configured Jira instance. In select cases where an instance has more than one Jira instance attached, a user may need to explicitly reference a Jira instance to properly render a Jira macro. Jira-related directives have the ability to reference Jira instances, with a combination of a UUID and name; for example:.. jira_issue:: TEST-151 :server-id: d005bcc2-ca4e-4065-8ce8-49ff5ac5857d :server-name: MyAwesomeJiraServer
It may be tedious for some projects to add this information in each document. As an alternative, a configuration can define Jira instance information inside a configuration option as follows:
confluence_jira_servers = { 'server-1': { 'id': '<UUID of Jira Instance>', 'name': '<Name of Jira Instance>', } }
With the above option defined in a project’s configuration, the following can be used instance inside a document:
.. jira_issue:: TEST-151 :server: server-1
- confluence_lang_transform¶
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
- 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
confluence_link_transform
.
- confluence_link_transform¶
A function to override the translation of a document name to a (partial) URI. The provided function is used to perform translations for both Sphinx’s get_relative_uri method. The default translation will be the combination of “
docname
+confluence_link_suffix
”.
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
See also
confluence_prev_next_buttons_location
.
- 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:
Deprecated options¶
- confluence_master_homepage¶
Changed in version 1.6.
This option has been renamed to
confluence_root_homepage
.
- confluence_publish_subset¶
Changed in version 1.3.
This option has been renamed to
confluence_publish_allowlist
.
- confluence_purge_from_master¶
Changed in version 1.6.
This option has been renamed to
confluence_purge_from_root
.
- confluence_space_name¶
Changed in version 1.7.
This option has been renamed to
confluence_space_key
.
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_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
andlabel-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::
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
orfalse
... jira:: project = "TEST" :count: true
- :maximum_issues: count (number)¶
The maximum number of issues a
jira
directive will display. By default, Confluence defaults to20
... jira:: project = "TEST" :maximum_issues: 10
- :server: instance (string)¶
Indicates a named Jira server provided via
confluence_jira_servers
(ref). When set, optionsserver-id
andserver-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 optionserver
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 optionserver
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, optionsserver-id
andserver-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 optionserver
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 optionserver
cannot be set... jira_issue:: TEST-123 :server-id: d005bcc2-ca4e-4065-8ce8-49ff5ac5857d :server-name: MyAwesomeJiraServer
See also Jira roles.
Roles¶
The following outlines additional roles supported by this extension.
Jira¶
The following roles 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.
See also Jira directives.
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 |
---|---|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Unsupported. Confluence markup does not permit the use of the
|
|
Supported |
|
Supported |
|
Limited support. Only auto-enumerator lists ( |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported with additional system tools. Requires a LaTeX and dvipng/dvisvgm installation. |
|
Supported |
|
Supported |
|
Supported |
|
Supported. Use the |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
(note: directive options “class” and “name” are ignored as they are not supported in a Confluence format document)
Sphinx markup¶
Type |
Notes |
---|---|
Supported |
|
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 The |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
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 |
---|---|
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 |
|
Supported |
|
Supported |
|
N/A |
|
Supported |
|
Supported |
|
Supported |
|
N/A |
|
Supported |
|
Supported |
|
N/A |
|
Supported |
|
Supported |
|
Limited support. Users should have no issues when using
external modules via |
|
Unsupported. Confluence does not support the injection of JavaScript into a page in most scenarios. |
|
Unsupported. This extension only supports injecting
references for the |
|
Unsupported. Confluence does not support the injection of JavaScript into a page in most scenarios. |
|
Supported |
|
Supported |
|
Unsupported. This extension only supports injecting
references for the |
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 |
---|---|
Limited support. Formatting of content may not be as expected. |
|
Supported |
|
Limited support. Formatting of content may not be as expected.
The |
|
Supported |
|
Supported. May require configuration of the
|
|
Limited support. PNGs only; cannot configure for SVG at this time. |
|
Limited support. PNGs only; cannot configure for SVG at this time. |
|
Supported |
|
Supported |
|
Supported |
|
Limited support. Requires a PNG/SVG configuration. |
|
Limited support. PNGs only; cannot configure for SVG at this time. |
|
Supported |
|
Supported. sphinxcontrib-plantuml provides its own support for this extension. |
|
Supported |
|
Limited support. PNGs only; cannot configure for SVG at this time. |
|
Supported |
|
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
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.
Recommended options for math¶
The following are recommended options to use when using sphinx.ext.imgmath:
imgmath_font_size = 14
imgmath_use_preview = True
imgmath_image_format = 'svg'
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).
Publishing with a CI secret key¶
Note
If running in a tox
/virtualenv
setup, ensure any environment
variables used are configured to be passed through to the virtual
environment.
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:
import os
...
confluence_server_pass = os.getenv('SECRET_KEY')
The above will read an environment variable SECRET_KEY
prepared by a CI
script which will be set on the confluence_server_pass
(ref) configuration.
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
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 ]------------
Changelog¶
1.7.0 (2021-11-21)¶
(note)
confluence_max_doc_depth
support is deprecated (reminder)confluence_space_name
renamed toconfluence_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 deprecatedconfluence_master_homepage
renamed toconfluence_root_homepage
confluence_purge_from_master
renamed toconfluence_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 buildsfixed 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 singlebuilderfixed 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
overconfluence
for raw typesupport
:stub-columns:
option in a list-table directivesupport 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 directivesupport 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.7improved 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 macrosupport 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
extensionsupport
sphinx.ext.todo
extensionsupport 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 directivesupport 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 homepagesupport 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 homepagesupport 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 aconfluence
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