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.

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.

Source Distribution

wikir-0.4.1.tar.gz (16.3 kB view details)

Uploaded Source

Built Distribution

wikir-0.4.1-py2.5.egg (34.4 kB view details)

Uploaded Source

File details

Details for the file wikir-0.4.1.tar.gz.

File metadata

  • Download URL: wikir-0.4.1.tar.gz
  • Upload date:
  • Size: 16.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for wikir-0.4.1.tar.gz
Algorithm Hash digest
SHA256 8e246a3ad704cc302db1dc7c915511ec41d0fa75b5c87f7f1124ee79547abd63
MD5 e4fa3305fea45f7a3bff8f1f26d4615c
BLAKE2b-256 057a7ed24995ecc0ba28c843cc49bc9317fb01d77266633f14574d0f90f8da9a

See more details on using hashes here.

File details

Details for the file wikir-0.4.1-py2.5.egg.

File metadata

  • Download URL: wikir-0.4.1-py2.5.egg
  • Upload date:
  • Size: 34.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for wikir-0.4.1-py2.5.egg
Algorithm Hash digest
SHA256 28bcc0936ac414f5ea09ebbfe9a285fd4caf62c5a557ee0b07f04de34fa11489
MD5 e820d71ee17dfc73aa42e3b0ca750a31
BLAKE2b-256 864f82b21062f44f822815d6791743552701c3b158fb29848dbd6cece0556519

See more details on using hashes here.

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