rst2wiki
========

rst2wiki is command line utility for pushing your documentation
in reStructuredText format to Confluence wiki. Under the covers
it uses `rst2confluence <https://github.com/netresearch/rst2confluence>`_
library for transforming ReST files and pushes result using
`Confluence REST API <https://docs.atlassian.com/atlassian-confluence/REST/latest/>`_.


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 <https://github.com/mitsuhiko/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.

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
