Atlassian Confluence Builder for Sphinx

Sphinx extension to build Confluence Wiki markup formatted files and optionally publish them to a Confluence server.

documentation contents

installing

Atlassian Confluence Builder for Sphinx depends on:

The recommended method of installation is using pip.

pip install --user sphinxcontrib-confluencebuilder

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

python -m sphinxcontrib.confluencebuilder --version

fresh quick-start

The following provides a series of steps to assist in preparing a new environment to use this package. This quick-start will aim to use the most recent version of Python.

Note

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

python -m pip install --upgrade 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 -S python-pip
$ pip install --user sphinxcontrib-confluencebuilder
$ python -m sphinxcontrib.confluencebuilder --version
sphinxcontrib.confluencebuilder <version>
centos
$ sudo yum install epel-release
$ sudo yum install python-pip
$ pip install --user sphinxcontrib-confluencebuilder
$ python -m sphinxcontrib.confluencebuilder --version
sphinxcontrib.confluencebuilder <version>
fedora
$ sudo dnf install python-pip
$ pip install --user sphinxcontrib-confluencebuilder
$ python -m sphinxcontrib.confluencebuilder --version
sphinxcontrib.confluencebuilder <version>
ubuntu
$ sudo apt-get install python-pip
$ pip install --user 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 --user sphinxcontrib-confluencebuilder
$ python -m sphinxcontrib.confluencebuilder --version
sphinxcontrib.confluencebuilder <version>
windows

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

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. Open a Python command environment from the start-menu or, if Python was added to the system path, open a Windows command prompt. Invoke the following:

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

master

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

pip install \
    git+https://github.com/tonybaloney/sphinxcontrib-confluencebuilder

tutorial

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

  • Allow a builder to generate Confluence-compatible markup documentation.
  • Allow a builder to publish to a Confluence instance.

Tip

If starting without an existing Sphinx-based documentation, open a terminal to the location where documentation should be generated and invoke the following to generate a new documentation project:

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

Enable the new builder by adding the new extension to 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_name = 'TEST'
# (for confluence cloud)
confluence_server_url = 'https://example.atlassian.net/wiki'
confluence_server_user = 'myawesomeuser@example.com'
confluence_server_pass = 'myapikey'
# (or for confluence server)
confluence_server_url = 'https://intranet-wiki.example.com'
confluence_server_user = 'myawesomeuser'
confluence_server_pass = 'mypassword'

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

If one wishes to publish documents as children of a parent page inside a space, the configuration confluence_parent_page should be supplied with the name of the page to append published documents. If omitted, the builder will publish documents in the root of the space. For example:

confluence_parent_page = 'MyDocumentation'

Tip

For additional configuration options, consult all configuration options.

Invoke Sphinx with the confluence builder to perform building/publishing:

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

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

configuration

The following is an example of simple configuration 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 = 'username'
confluence_server_pass = 'password'

All Atlassian Confluence Builder configurations are prefixed with confluence_. 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 one wishes to publish content. By default, the value is set to False.

confluence_publish = True
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 (if supported) for the configured username value (see api_tokens). If API tokens are not being used, the plain password for the configured username value should be used.

confluence_server_pass = 'vsUsrSZ6Z4kmrQMapSXBYkJh'
    (or)
confluence_server_pass = 'myawesomepassword'
confluence_server_url

The URL for Confluence. The URL should be prefixed with https:// or http:// (depending on the URL target). The target API folder should not be included in the URL (for example, excluding /rest/api/ or /rpc/xmlrpc/). 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/ or XML-RPC API is at https://intranet-wiki.example.com/rpc/xmlrpc, should be as follows:

confluence_server_url = 'https://intranet-wiki.example.com'
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_space_name

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

confluence_space_name = 'MyAwesomeSpace'

general configuration

confluence_disable_notifications

A boolean value which explicitly disable 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
confluence_header_file

The name of the file to use header data. If provided, the 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'
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_max_doc_depth

An 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 defining a value of 0, all child pages of the root document will be merged into a single document. By default, the maximum document depth is disabled with a value of None.

confluence_max_doc_depth = 2
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, the hierarchy mode is disabled with a value of False.

confluence_page_hierarchy = False

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 based off the configured (or unconfigured) confluence_parent_page setting.

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, 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 the MyAwesomeDocs page:

confluence_parent_page = 'MyAwesomeDocs'

If a parent page is not set, consider using the confluence_master_homepage option as well.

confluence_publish_prefix

If set, the prefix value is added to the title of all published document. 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 each with their own prefix value.

An example publish prefix is as follows:

confluence_publish_prefix = 'prefix-'
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 to True, detected pages in Confluence that do not match the set of published documents will be automatically removed. If the option confluence_parent_page is set, only pages which are a descendant of the configured parent page can be removed; elsewise, all 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.

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 to True. 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 still requires confluence_purge to be set to True before taking effect.

confluence_purge_from_master = False

advanced configuration - processing

confluence_file_suffix

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

confluence_file_suffix = '.conf'
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_lang_transform

A function to override the translation of literal block-based directive language values to Confluence-support 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_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

advanced configuration - publishing

confluence_ca_cert

Provide a CA certificate to use for server cert authentication. Can either be a file or a path. If you are using the rest interface, refer to the Requests CA docs for information on what is supported. If you are using the XML-RPC interface, refer to the SSL CA docs. By default, verification is turned on and can be turned off with the confluence_disable_ssl_validation config option. If it is turned off, this option is ignored.

confluence_ca_cert = os.path.join('path', 'to', 'ca.crt')
confluence_client_cert

Provide a client certificate to use for two-way TLS/SSL authentication. Can either be a single file (containing the private key and the certificate) or as a tuple of both file’s paths. If the certificate is encrypted, you will be prompted for a password during the publishing step.

confluence_client_cert = os.path.join('path', 'to', 'cert_and_key.pem')
# or
confluence_client_cert = ('client.cert', 'client.key')
confluence_client_cert_pass

Provide a password for the confluence_client_cert. This prevents a prompt from requesting your client certificate password. If your client certificate is unencrypted, this value will be ignored.

confluence_client_cert_pass = 'password'
confluence_disable_autogen_title

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

confluence_disable_autogen_title = True
confluence_disable_rest

A boolean value to explicitly disable any REST API calls. This extension has the ability to publish using either Confluence’s REST or XML-RPC API calls. When publishing, this extension will first attempt to publish using REST and fallback to using XML-RPC. If the target Confluence instance cannot use REST for publishing, it is recommended to set the option to True to always use XML-RPC instead. By default, this option is set to False.

confluence_disable_rest = False
confluence_disable_ssl_validation

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_disable_xmlrpc

A boolean value to explicitly disable any XML-RPC API calls. This extension has the ability to publish using either Confluence’s REST or XML-RPC API calls. When publishing, this extension will first attempt to publish using REST and fallback to using XML-RPC. If the target Confluence instance supports REST or has XML-RPC explicitly disabled, it is recommended to set this option to True. By default, this option is set to False.

confluence_disable_xmlrpc = False
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 server. This serves as a sanity-check configuration for the cautious.

confluence_parent_page_id_check = 1
confluence_proxy

Provide the proxy needed to be used to interact with the Confluence server over the network. At this time, the proxy configuration only applies to XML-RPC calls (REST calls use the Requests library which will use system-defined proxy configuration).

confluence_proxy = 'myawesomeproxy:8080'
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 and other implementations). By default, assume that any network interaction will not timeout. Since the target Confluence server 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

markup

The following outlines the reStructuredText / Sphinx markup explicitly supported by this extension. The intent of this extension is to support as much markup as possible that can be rendered on a Confluence instance. Below will identify markup that has been tested, planned to be implemented in the future or is not compatible with Confluence.

standard

type status notes
admonitions completed
bibliographic fields planned
block quotes partial
bullet lists completed
centered unsupported
citations completed
code partial
  • Sphinx Code Markup
  • code-block options emphasize-lines and lines as well as highlight option linenothreshold are ignored due to incompatibilities with Confluence’s code block macro.
  • Highlighting is limited to languages defined by the Confluence instance (see code block macro).
  • Pending work to validate/improve code block options caption, encoding and pyobject.
compound paragraph completed
container prospect
definition lists completed
deprecated completed
enumerated lists completed
epigraph prospect
footnotes completed
glossary partial
  • Sphinx Glossary
  • Visually renders definitions; references to entries not yet supported.
highlights prospect
hlist unsupported
hyperlink targets completed
images prospect
list table partial
literal blocks completed
math unplanned
option lists planned
production list planned
pull-quote prospect
raw planned
rubric completed
sections completed
tables partial
toctree partial
transitions completed
versionadded completed
versionchanged completed

(note: directive options “class” and “name” are ignored)

extensions

This extension has currently no official support for other Sphinx extensions at this time.

There is plans to support the following extensions in the future:

other

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

Atlassian Confluence Builder for Confluence - Issues
https://github.com/tonybaloney/sphinxcontrib-confluencebuilder/issues

documentation

Documentation for Atlassian Confluence Builder is made with Sphinx and distributed on Read the Docs. Sources of the documentation can be found inside the package repository’s doc folder:

Atlassian Confluence Builder for Confluence
https://github.com/tonybaloney/sphinxcontrib-confluencebuilder

The documentation theme used by default is set to sphinx_rtd_theme. If locally generating documentation, the theme can be installed on systems using the following command:

pip install --user sphinx_rtd_theme

changelog

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 hightlight directive
  • support maximum page depth (nesting documents)
  • support the raw directive
  • support two-way ssl connections

0.8.0 (2017-12-05)

  • fix case where first-publish with ‘confluence_master_homepage’ fails to configure the space’s homepage
  • support page hierarchy
  • Improve PyPi cover notes

0.7.0 (2017-11-30)

  • cap headers/sections to six levels for improved visualization
  • fixed rest publishing for encoding issues and python 3.x (< 3.6) issues
  • improve markup for:
    • body element lists
    • citations
    • definitions
    • footnotes
    • inline literals
    • literal block (code)
    • rubric
    • seealso
    • table
    • versionmodified
  • re-work generated document references/targets (reference to section names)
  • sanitize output to prevent confluence errors for certain characters
  • support indentations markup
  • support master_doc option to configure space’s homepage
  • support removing document titles from page outputs
  • support silent page updates

0.6.0 (2017-04-23)

  • cleanup module’s structure, versions and other minor files
  • drop ‘confluence’ pypi package (embedded xml-rpc support added)
  • improve hyperlink and cross-referencing arbitrary locations/documents support
  • improve proxy support
  • re-support python 3.x series
  • support anonymous publishing
  • support rest api

0.5.0 (2017-03-31)

  • header/footer support
  • purging support
  • use macros for admonitions
  • (note) known issues with python 3.3, 3.4, 3.5 or 3.6 (see tonybaloney/sphinxcontrib-confluencebuilder#10)

0.4.0 (2017-02-21)

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