Skip to main content

Publish RST documents in Wiki format.

Project description

Summary

Wikir (pronounced “wicker”) converts reStructuredText documents to various Wiki formats. Currently, Google Code Wiki Syntax is the target, but compatibility with Moin Moin Wiki Syntax and Trac Wiki Syntax is maintained when possible.

Installation

easy_install wikir

Or check out a development version from the subversion repository.

How Much reStructuredText Is Supported?

Not a whole lot! Since RST syntax is huge and Google Code Wiki Syntax is small, RST may never be fully supported. However, if you come across an unsupported RST directive please submit an issue and include the snippet of RST and how you think it should be displayed in wiki syntax.

Is possible, also submit a failing test for the new syntax you’d like supported. You can see all currently tested and implemented RST syntax elements by running the following command (requires nose):

nosetests -v -a syntax -a '!deferred'

Remove the -a '!deferred' to see those that still need implementing. Patches gladly accepted ;)

Using Wikir In Your Project

The publish_wiki Command

After installing wikir, all setuptools-enabled projects on the same machine will grow a new command, publish_wiki. A setuptools project is one with a setup.py file like so:

from setuptools import setup
setup(
    name='MyModule',
    version='0.999',
    # ...etc...
)

Command usage:

$ python setup.py publish_wiki --help
| Global options:
|   --verbose (-v)  run verbosely (default)
|   --quiet (-q)    run quietly (turns verbosity off)
|   --dry-run (-n)  don't actually do anything
|   --help (-h)     show detailed help message
|
| Options for 'publish_wiki' command:
|   --source (-s)  path to RST source.  if a python module, the top-most
|                  docstring will be used as the source
|
| usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
|    or: setup.py --help [cmd1 cmd2 ...]
|    or: setup.py --help-commands
|    or: setup.py cmd --help
|

Publishing RST To Wiki

Here is an example of publishing a module’s docstring written in RST format to Wiki format:

$ cd examples/basic
$ cat ./akimbo/__init__.py
| '''
| Welcome To Akimbo
| =================
|
| A Python module for akimbo'ing.
|
| This could live on `Google Code`_ if it wanted to.
|
| .. _Google Code: http://code.google.com/hosting/
|
| '''
$ python setup.py publish_wiki --source=./akimbo/__init__.py
| = Welcome To Akimbo =
|
| A Python module for akimbo'ing.
|
| This could live on [http://code.google.com/hosting/ Google Code] if it wanted to.
|

Using Custom RST Directives

Wikir provides an entry_point in case you need to register a custom RST directive. Here is an example:

$ cd examples/custom_directives
$ python setup.py -q develop
$ cat setup.py
| from setuptools import setup
| setup(
|     name = 'Foozilate',
|     entry_points = {
|         'wikir.rst_directives': [
|             'foozilate = foozilate.directives:foozilate'
|         ]
|     },
|     description = "A mysterious package that aids in foozilation")
$ cat ./README.txt
| This is the documentation for foozilate, which requires a custom directive called ``foozilate``.  All it does is wrap some tags around the input.
|
| .. foozilate::
|     this should be foozilated
$ python setup.py publish_wiki --source ./README.txt
| This is the documentation for foozilate, which requires a custom directive called `foozilate`.  All it does is wrap some tags around the input.
|
| --foozilated-- this should be foozilated --foozilated--
|
$ python setup.py -q develop --uninstall

The left side of the entry_point defined the directive name and the right side specified the path to the directive function. This is registered with docutils before any RST is published.

Using Wikir Programatically

>>> from wikir import publish_string
>>> print publish_string('''
... My RST Document
... ===============
...
... For `Google Code`_!
...
... .. _Google Code: http://code.google.com/
... ''')
= My RST Document =
<BLANKLINE>
For [http://code.google.com/ Google Code]!
<BLANKLINE>
<BLANKLINE>
>>>

Credits

This work is based on code I found while snooping around the nose repository (Jason Pellerin), Ian Bicking’s docutils sandbox, and Matthew Gilbert’s docutils sandbox. Thanks to Kent S. Johnson for additional help and feedback.

Project Home

If you’re not there already, wikir lives on Google Code.

Project details


Download files

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

Source Distribution

wikir-0.1.tar.gz (14.2 kB view hashes)

Uploaded Source

Built Distribution

wikir-0.1-py2.4.egg (30.4 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page