Skip to main content

Atlassian Confluence extension for sphinx

Project description

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

Project details


Release history Release notifications

This version
History Node

0.0.3

History Node

0.0.2

History Node

0.0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
sphinx_confluence-0.0.3-py2.py3-none-any.whl (11.0 kB) Copy SHA256 hash SHA256 Wheel py2.py3 Sep 15, 2016

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page