Skip to content

Arello-Mobile/sphinx-confluence

Repository files navigation

Sphinx Confluence Plugin

Build Status

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:

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