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.