tutorial

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

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

new documentation

If starting without an existing Sphinx-based documentation, one can create a minimalistic Sphinx configuration or use Sphinx’s quick-start utility.

quick-start

If opting for the quick-start utility, open a terminal to the location where documentation should be generated 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 this project’s configuration by consulting the existing documentation steps (below).

minimalistic

For a minimalistic setup, create a new folder for the new documentation and configuration to be used. Create a document named index.rst with the following content:

my documentation
================

This is a test document.

Next, create a configuration file with the following information:

# -*- coding: utf-8 -*-

extensions = ['sphinxcontrib.confluencebuilder']

After preparing these assets, consult the existing documentation steps (below) to complete the configuration.

existing documentation

Enable this extension’s builder by adding the 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.

Tip

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

If one wishes to publish documents as children of a parent page inside a space, the configuration confluence_parent_page (jump) 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'

To process and publish the documentation set, invoke Sphinx with the confluence 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.