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.