Tutorial

Note

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

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

  • Enables a user to generate Confluence-compatible markup documentation.

  • Enables a user to publish to a Confluence instance.

New documentation

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

Quick-start

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

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

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

Minimalistic

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

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

This is a test document.

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

extensions = []

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

Configuring to use this extension

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

extensions = [
    'sphinxcontrib.confluencebuilder',
]

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

confluence_publish = True
confluence_space_key = 'TEST'
confluence_ask_password = True
# (for Confluence Cloud)
confluence_server_url = 'https://example.atlassian.net/wiki/'
confluence_server_user = 'myawesomeuser@example.com'
# (or, for Confluence Data Center)
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).

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.