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.
If 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 ./wikir/tests/test_syntax.py -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 | Common commands: (see '--help-commands' for more) | | setup.py build will build the package underneath 'build/' | setup.py install will install the package | | 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 specifies the path to the directive function. This is registered with docutils before any RST is published.
The wikir command
If you don’t want to use wikir through setup.py you can use the command line script, wikir, which gets installed for you.
Command usge:
$ wikir --help | Usage: wikir [options] path/to/module.py | wikir [options] path/to/file.txt | | Publish RST documents in Wiki format | | 1. finds the top-most docstring of module.py, parses as RST, and prints Wiki format to STDOUT | 2. parses file.txt (or a file with any other extension) as RST and prints Wiki format to STDOUT | | Options: | -h, --help show this help message and exit
You can publish a module’s docstring written in RST format to Wiki format like so:
$ 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/ | | ''' $ wikir ./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. |
… and you can publish any document written in RST format to Wiki format like so:
$ cd examples/basic $ cat ./README.txt | ======================== | Documentation for Akimbo | ======================== | | .. contents:: :local: | | What is it? | =========== | | A Python module for akimbo'ing. | | Where does it live? | =================== | | Akimbo could live on `Google Code`_ if it wanted to. | | .. _Google Code: http://code.google.com/hosting/ $ wikir ./README.txt | = Documentation for Akimbo = | | * What is it? | * Where does it live? | | | = What is it? = | | A Python module for akimbo'ing. | | = Where does it live? = | | Akimbo could live on [http://code.google.com/hosting/ Google Code] if it wanted to. |
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.