rst2wiki 0.3.1

Tool to push reST docs to confluence

rst2wiki is command line utility for pushing your documentation in reStructuredText format to Confluence wiki. Under the covers it uses rst2confluence library for transforming ReST files and pushes result using Confluence REST API.

Installation

It is available through PyPI:

pip install rst2wiki

or getting more popular recently:

python -m pip install rst2wiki

Personally, I recommend to use pipsi:

pipsi install rst2wiki

It works under Mac OS X and Linux on Python versions 2.7 and 2.6.

Usage

rst2wiki supports two use cases: (1) updating existing page in Confluence and (2) creating new page.

First time it will ask you for some configuration values: Confluence url (don’t forget https:// part), your login and password and store it for further usage (password storage is optional).

Assuming you want to create page first from your ReST source, invocation could be as follows (note option --create):

rst2wiki --create --ancestor 1147842 --title 'Project overview' documentation.rst

Most options are, not surprisingly, optional.

Ancestor option takes page id, under which you want to place new page (it will be parent to new page, so to speak). If not presented, page will be created in your personal space. Page id of existing page you can find in URL of page, after you click on ‘Edit’ (in some cases Confluence shows page id without any tricks – if it was set up to do so or page has some unicode symbols in title).

Title option sets header of new page in Confluence. If not specified in command line, tool takes first heading of document as option value.

Update of page is executed as follows (page id in this case is mandatory):

rst2wiki --page 10814244 --ancestor 1147842 documentation.rst

Sadly, Confluence REST API for current version (5.8.6) does not return ancestors in page resource representation, so we need to provide it every time on page update or our updated page will move to space’s root.

There are some more options: --warning (adds warning to top of your page that this page is autogenerated and manual revisions will be overwritten), --title to update page title in confluence (use exiting, if not specified) and --config for configuration file location.

More interesting, it is possible to embed all arguments (except config and create) in ReST document by adding comment in the following form:

.. rst2wiki

  :page: 10814244
  :ancestor: 1147842
  :title: Project overview
  :warning: en

After that you can use tool as follows:

rst2wiki documentation.rst

Of course, you still can override document metadata in command line:

rst2wiki --warning off documentation.rst