Package: wikir
ContentsSummaryInstallationHow Much reStructuredText Is Supported?Using Wikir In Your ProjectThe publish_wiki CommandPublishing RST To WikiUsing Custom RST DirectivesThe wikir commandUsing Wikir ProgramaticallyCreditsProject HomeSummaryWikir (pronounced “wicker”) convertsreStructuredTextdocuments to various Wiki formats.  Currently,Google Code Wiki Syntaxis the target, but compatibility withMoin Moin Wiki SyntaxandTrac Wiki Syntaxis maintained when possible.Installationeasy_install wikirOr check out a development version from thesubversion repository.How Much reStructuredText Is Supported?Not a whole lot!  SinceRST syntaxis huge andGoogle Code Wiki Syntaxis small, RST may never be fully supported.  However, if you come across an unsupported RST directive pleasesubmit an issueand 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 (requiresnose):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 ProjectThe publish_wiki CommandAfter installing wikir, allsetuptools-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 WikiHere 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 DirectivesWikir provides an entry_point in case you need to register acustom 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 --uninstallNoteYou 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 theThe Cheeseshopor another documentation generator, likepydoctor.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 commandIf 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 exitYou 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>
>>>CreditsThis work is based on code I found while snooping around thenose repository(Jason Pellerin),Ian Bicking’s docutils sandbox, andMatthew Gilbert’s docutils sandbox.  Thanks toKent S. Johnsonfor additional help and feedback.Project HomeIf you’re not there already,wikir lives on Google Code.