mbeacom/sphinx-confluence

Atlassian Confluence extension for sphinx

Sphinx Confluence Plugin

Sphinx extension for making the documentation compatible with the Confluence Storage Format.

Features:

• base HTML elements
• images (image, figure)
• code blocks (::) and includes (literalinclude)
• referencing downloadable files (:download:)
• the TOC tree (.. toctree::)
• internal links (:ref: <label>; .. _)
• Inline and table Jira Issues
• Reference for Confluence User
• Info, Tip, Note, and Warning Macros

Why?

This extension is written as part of our Documentation Toolkit which we use in our job daily. The main idea of toolkit is to make a process of creating and updating documentation able to be automated

Other parts of our toolkit is:

• py2swagger
• swagger2rst
• sphinx-confluence
• confluence-publisher

Install

Install Sphinx Confluence Plugin from PyPI with

$ pip install sphinx-confluence

How use it

First of all, after installation, you must enable this plugin in your build configuration file conf.py by adding sphinx_confluence into extensions list. This should looks like a:

...
extensions = ['sphinx_confluence']
...

Then you can build you documentation into html or json formats, either by using sphinx build command or if you uses sphinx-quickstart script by following commands:

• make html
• make singlehtml
• make json

After that, the results must be in Confluence Storage Format. You can use confluence-publisher for publish them to your Confluence.

Additional Markup Constructs

Sphinx Confluence Plugin adds few new directives to standard reST markup.

Jira Issues

Inline

Lorem ipsum dolor sit amet, :jira_issue:`PROJECT-123` consectetur adipiscing elit

Table View

Markup:

.. jira_issues:: <JQL query>
   :anonymous: 'true'|'false' (default: 'false')
   :server_id: 'string' (default: '')
   :baseurl: 'string' (default: '')
   :columns: A list of JIRA column names, separated by semi-colons (;)
   :count: 'true'|'false' (default: 'false')
   :height: int (default: 480)
   :title: 'string' (default: '')
   :render_mode: 'static'|'dynamic' (default: 'static')
   :url: 'string' (default: '')
   :width: '{x}px' | '{x}%' (default: '100%')
   :maximum_issues: int (default: 20)

Example:

.. jira_issues:: project = PROJ AND issuetype = Epic AND resolution = Unresolved
   :title: Unresolved project epics
   :columns: type;key;summary;status;created;
   :width: 80%

Jira Users

Lorem ipsum dolor sit amet, :jira_user:`username` consectetur adipiscing elit