This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
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

Note

You should avoid putting custom directives in a docstring if you want them to build with a standard docutils install. For example, your RST docstrings may be parsed automatically by the The Cheeseshop or another documentation generator, like pydoctor.

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.

Release History

Release History

0.4.1

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
wikir-0.4.1-py2.5.egg (34.4 kB) Copy SHA256 Checksum SHA256 2.5 Egg May 15, 2009
wikir-0.4.1.tar.gz (16.3 kB) Copy SHA256 Checksum SHA256 Source May 15, 2009

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting