Configuration¶
The following is an example of simple configuration (config.py
) for
Confluence generation and publishing:
extensions = ['sphinxcontrib.confluencebuilder']
confluence_publish = True
confluence_space_name = 'TEST'
confluence_parent_page = 'Documentation'
confluence_server_url = 'https://intranet-wiki.example.com/'
confluence_server_user = 'myawesomeuser'
confluence_server_pass = 'myapikey'
confluence_page_hierarchy = True
All configurations introduced by this extension are prefixed with
confluence_
. This extension may take advantage of a subset of
Sphinx configurations as well when preparing documents. View the entire list
of configuration options below.
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_name
¶ Note
The space name is case-sensitive.
Key of the space in Confluence to be used to publish generated documents to.
confluence_space_name = 'MyAwesomeSpace'
-
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
¶ 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'
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
).
Generic configuration¶
-
confluence_add_secnumbers
¶ New in version 1.2.
Add section numbers to page and section titles if
doctree
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_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_max_doc_depth
¶ 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 master_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
Important
This feature still supports a document depth of
0
, where all child pages of the root document will be merged into a single document. Setting this value to0
is considered deprecated. An alternative approach to generating a single document page is to use thesingleconfluence
builder instead.
-
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 master_doc. If a master_doc instance contains a toctree, listed documents will become child pages of the master_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 master_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.
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
.
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_master_homepage
¶ 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 master_doc. By default, the master_doc configuration is ignored with a value of
False
.confluence_master_homepage = False
-
confluence_parent_page
¶ The root page found inside the configured space (
confluence_space_name
) 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_master_homepage
option as well. Note that the page’s name can be case-sensitive in most (if not all) versions of Confluence.
-
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_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_master
¶ A boolean value to which indicates that any purging attempt should be done from the root of a published master_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 master_doc page. This option requiresconfluence_purge
to be set toTrue
before taking effect.confluence_purge_from_master = False
See also
confluence_purge
.
-
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
¶ 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_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_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)
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
”.
-
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_publish_subset
¶ Changed in version 1.3.
This option has been renamed to
confluence_publish_allowlist
.