Confluence¶

Currently a lot of documentation is maintained in Confluence. But it is disconnected from the source code and other information in the source code repository.

There are several tools to convert to and from Confluence Storage Format

Export to Confluence¶

There are several tools (including a Sphinx extension ) that can create Confluence format documentation and publish to Confluence.

Confluence Builder for Sphinx¶

This Sphinx extension

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

See example test output and a demo video:

Authentication for Confluence Cloud and Confluence Server may be different.

Confluence Cloud¶

For Confluence Cloud, an api token can used for the password in conf.py

confluence_server_pass = APITokenValue

An API token can be obtained for your cloud hosted Confluence site from https://id.atlassian.com/manage/api-tokens.

Confluence Server¶

ref confluence_server_url,

confluence_publish = True
confluence_space_name = 'docdac'
#confluence_parent_page = 'overview'
confluence_server_url = 'https://confluence.company.com'
confluence_server_user = 'user'
# confluence_server_pass = 'password'
confluence_ask_password = True

Sanity check with curl¶

ref https://developer.atlassian.com/server/confluence/confluence-rest-api-examples/

curl -u user:password https://confluence.company.com:8443/rest/api/content/  | python -m json.tool

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                             Dload  Upload   Total   Spent    Left  Speed
100 17072    0 17072    0     0  11971      0 --:--:--  0:00:01 --:--:-- 11963
{
    "_links": {
        "base": "https://confluence.company.com:8443",
        "context": "",
        "next": "/rest/api/content/?limit=25&start=25",
        "self": "https://confluence.company.com:8443/rest/api/content/"
    },
    "limit": 25,

curl -u user:password https://confluence.company.com:8443/display/docdac/rest/api/content/

Import from Confluence¶

In general there’s 2 ways to do this:

Export from Confluence
Scrape pages from Confluence

Export from Confluence¶

Confluence Export Content to XML exports pages in the Confluence Storage Format (which is XHTML based, i.e. valid XML). These can then be transformed into Markdown (or ReST) using XSLT.

There’s several tools available for this:

Pandoc¶

Some examples of projects that used Pandoc to convert from Confluence to RST:

http://udig-news.blogspot.com/2012/10/how-to-convert-from-confluence-to-sphinx.html
https://jira.lsstcorp.org/browse/DM-5013 who went from https://confluence.lsstcorp.org/display/LDMDG#/ to https://developer.lsst.io/
https://www.npmjs.com/package/confluence-to-github-markdown I’ve used this in the past. It works but does need some cleanup (which can be automated).