wikir 0.4.1

The publish_wiki Command

安装wikir后，同一台计算机上所有启用setuptools的项目都将生成一个新命令publish_wiki。setuptools项目是一个包含setup.py文件的项目，如下所示：

from setuptools import setup
setup(
    name='MyModule',
    version='0.999',
    # ...etc...
)

命令用法：

$ 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

下面是将以rst格式编写的模块docstring发布为wiki格式的示例：

$ 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提供了一个入口点，以防需要注册custom RST directive。下面是一个例子：

$ 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

入口点的左侧定义了指令名，右侧指定了指令函数的路径。在发布任何RST之前，都会向docutils注册

The wikir command

如果不想通过setup.py使用wikir，可以使用为您安装的命令行脚本wikir。

命令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

可以将以RST格式编写的模块docstring发布为Wiki格式，如下所示：

$ 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.
|

…并且您可以将以rst格式编写的任何文档发布为wiki格式，如下所示：

$ 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.
|