wikir 0.4.1

publish_wiki命令

安装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
|

将RST发布到Wiki

这是一个将模块的docstring以RST格式发布到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.
|

使用自定义RST指令

Wikir提供了一个入口点，以便您需要注册自定义RST指令时使用。以下是一个示例：

$ 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注册。

wikir命令

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

命令用法

$ 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

您可以将模块的docstring以RST格式发布到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.
|