September 2014 Blog Posts

将自己写的Python代码打包放到PyPI上

MitchellChu 2014-09-09 其他技术

如果是开源的代码,为了能够让大家更方便的使用,放到PyPI上也许是个非常不错的主意(PyPI:Python Package Index)。刚开始我以为要将代码打包放到PyPI上是一件非常复杂繁琐的事情,不过看过《Dive Into Python 3》的PACKAGING PYTHON LIBRARIES介绍(CHAPTER 16),并自己动手操作了一下,发现打包发布这个事情并没有想象中的那么有难度。为了方便其他朋友阅读的方便,就尝试写了这个博文,来记录下如何将自己写的Python代码打包上传到PyPI上。

在Python的世界里,有个叫的工具模块可以帮我们轻松的解决这个问题,既然这样,让我们开始打包之旅吧。

要打包代码,首先你的确保你的代码得是个包。比如,你写了一些功能的代码块,为了方便引用,你就需要将代码变成一个包,下次需要使用的时候,直接引用这个包里面的某个具体功能就好了。在Python中,要将这些代码变成包非常容易,你的这些功能的合集,可以用一个你觉得合适的名称来命名,创建这个命名的文件夹,并在文件夹下创建一个__init__.py文件,剩余的就是将你这些代码放入到这个文件夹下面即可。整理成包的文件结构大概像下面这样:

somefunctions/
    |
    +-- __init__.py
    |
    +-- myscripts1.py
    |
    +-- mysscripts2.py
    |
    +-- mymorescripts.py
    |

somefunctions就是你包的名称,下面my***.py的各种文件就是你原有的各种代码模块。是不是很简单就将自己的代码变成了包?确实很简单,你这步就是新建一个文件夹,把文件全放进去而已——哦,还有添加个__init__.py文件(文件内容可以为空).

到这里,我们已经有Python包了,如果不传到上的话,你都可以直接用了,最直接的方法是将这个文件夹拷到你的项目目录下,然后在项目代码里,你大概就能引用它了:

import somefunctions

module = somefunctions.myscripts1

### 这里你就可以调用myscripts1里面的功能了.

当然,我们的目标是到PyPI上,而不是将这个包拷来拷去的,后面安装一下,引用起来将更加的方便。

好了,既然要放到PyPI上,那么我们就需要在上面的基础上,在加点料。首先,我们需要调整下文件的目录结构,把上面的改成下面这个样子:

somefunctions/
    |
    +-- somefunctions/
    .       |
    .       +-- __init__.py
    .       |
    .       +-- myscripts1.py
    .       |
    .       +-- mysscripts2.py
    .       |
    .       +-- mymorescripts.py
    .       |
    .
    |

就是将原来的目录深移一层,文件夹名称一样即可。这步也不难吧。好吧,然后在到第一层的目录下创建些特殊文件,具体你可以看看下面这个文件结构你就明白了:

somefunctions
    |
    +-- COPYING.txt
    |
    +-- README.txt
    |
    +-- setup.py
    |
    +-- somefunctions
    .       |
    .       +-- __init__.py
    .       |
    .       +-- myscripts1.py
    .       |
    .       +-- mysscripts2.py
    .       |
    .       +-- mymorescripts.py
    .       |
    .
    |
    +-- docs/
    |

哇,咋一看,变了好多啊,其实不多,解释下:

TIPS:

  1. COPYING.txt 就是授权文件,里面是你关于这个包的授权,比如:MIT license,那么你里面放入MIT License全文即可,当然,如果你不清楚这个,你完全可以不要这个文件。
  2. README.txt,这个文件想必研发都应该清楚。如果有,尽量放些东西在这里了,后面如果可能我们会用到它的。需要注意的是,Windows的回车和Linux不一样,所以建议用Windows的好了。另外你也可以使用README.rst这类文件表示(reStructuredText文件,如果不清楚可以参看我前面几篇文章:入门Emacs快捷键
  3. setup.py,核心文件,这里面的内容马上我们会讲。
  4. docs/,这个文件夹你放你的documents吧,不过要用心写文档真是个难事,所以这个文件夹基本是不存在的——为自己的懒惰可耻一把。
  5. 如果的包整个就一个文件,那么你也完全可以不用考虑再建一层目录了,直接放到README文件所在目录下就可以了,虽然我不建议这么操作。

好了,文件都建好了,再来进化下,我们为setup.py填上内容,让我们的setup.py真正的能用起来,注意哦,前面没distutils什么事情,他的作用在这里哦。放出一个setup.py的Demo:

import codecs
import os
import sys

try:
    from setuptools import setup
except:
    from distutils.core import setup
"""
打包的用的setup必须引入,
"""

def read(fname):
    """
    定义一个read方法,用来读取目录下的长描述
    我们一般是将README文件中的内容读取出来作为长描述,这个会在PyPI中你这个包的页面上展现出来,
    你也可以不用这个方法,自己手动写内容即可,
    PyPI上支持.rst格式的文件。暂不支持.md格式的文件,<BR>.rst文件PyPI会自动把它转为HTML形式显示在你包的信息页面上。
    """
    return codecs.open(os.path.join(os.path.dirname(__file__), fname)).read()



NAME = "somefunctions"
"""
名字,一般放你包的名字即可
"""

PACKAGES = ["somefunctions",]
"""
包含的包,可以多个,这是一个列表
"""

DESCRIPTION = "this is a test package for packing python liberaries tutorial."
"""
关于这个包的描述
"""

LONG_DESCRIPTION = read("README.rst")
"""
参见read方法说明
"""

KEYWORDS = "test python package"
"""
关于当前包的一些关键字,方便PyPI进行分类。
"""

AUTHOR = "MitchellChu"
"""
谁是这个包的作者,写谁的名字吧
我是MitchellChu,自然这里写的是MitchellChu
"""

AUTHOR_EMAIL = "youremail@email.com"
"""
作者的邮件地址
"""

URL = "http://blog.useasp.net/"
"""
你这个包的项目地址,如果有,给一个吧,没有你直接填写在PyPI你这个包的地址也是可以的
"""

VERSION = "1.0.1"
"""
当前包的版本,这个按你自己需要的版本控制方式来
"""

LICENSE = "MIT"
"""
授权方式,我喜欢的是MIT的方式,你可以换成其他方式
"""

setup(
    name = NAME,
    version = VERSION,
    description = DESCRIPTION,
    long_description = LONG_DESCRIPTION,
    classifiers = [
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python',
        'Intended Audience :: Developers',
        'Operating System :: OS Independent',
    ],
    keywords = KEYWORDS,
    author = AUTHOR,
    author_email = AUTHOR_EMAIL,
    url = URL,
    license = LICENSE,
    packages = PACKAGES,
    include_package_data=True,
    zip_safe=True,
)

## 把上面的变量填入了一个setup()中即可。

你如果需要写一个setup.py文件,但又不会写,没关系,上面的复制一下,把信息改成你的,而后直接保存就可以了。Easy way to do this。

TIPS:

  1. 文中的classifiers的内容并不是随便填写的,你需要参照本文参考文档中的PyPI Classifiers来写。
  2. setup.py就是个Python代码,在这里面理论上你可以做任何Python能够做的事情,不过,为了保证正确性和简洁,我建议尽量少些复杂代码,毕竟就是个大包的代码,搞得太复杂了反而不好。
  3. 一般情况下,Distutils只会包含你包文件夹内的:README.txt,setup.py,packages里面定义的所有某块的.py文件,py_modules参数包含的所有.py文件,其他文件需要被包含进来,需要单独添加。需要添加,你可以在根目录添加一个MANIFEST.in文件,将要包含的文件放入,具体规则请参考官方文档格式。如我们这里需要添加COPYING.txt可以在MANIFEST.in中添加如下行:
    include COPYING.txt

setup.py写完之后,为了保证效果,我们可以检查下,当然不是让你去读代码,因为我们写的这些东西是要给Distutils看的,所以用它来检查最合适不过了,在命令行下输入:

## 直接路由到你写的setup.py文件的更目录下
## 然后运行:
python setup.py check

## 输出一般是running check
## 如果有错误或者警告,就会在此之后显示
## 没有任何显示表示Distutils认可你这个setup.py文件。

 如果有错误输出,按照显示进行修改即可,到没有任何异常输出的时候,你就可以开始创建你的了。打包也仅仅是个命令而已:

## 和上面一样,路由到setup.py所在目录
## 也是使用setup.py本身代码来运行
## 不同的是后面的参数不一样。

python setup.py sdist

## 命令执行后会输出打包的状态,你可以进行查看
## 如果有warning的话,你可以稍后返回修改对应的地方后,重新打包
## 如果正常的情况下,你应该可以在你的根目录下看到一个dist/的文件夹
## 文件夹里面包含了当前打包出来的一个.zip文件。或者.tar.gz文件.

 一路下来,我们获得了可以分发的包了,接下来,我们要做的就是将这个包放到PyPI上去了。

我们在做这步前,建议你先到PyPI上注册个帐号,这样方便些,当然,你也可以不注册,后面的步骤中会有提示,根据提示进行也可以。——本文按照先在PyPI上注册过帐号的方式进行。

我们有了PyPI的帐号,那么我们开始吧,离成功仅一步之遥了。在你包的根目录下,运行下面的Shell命令:

## 注册,并上传sdist

python setup.py register sdist upload

系统会提示类似下面信息:

running register
We need to know who you are, so please choose either:
 1. use your existing login,
 2. register as a new user,
 3. have the server generate a new password for you (and email it to you), or
 4. quit
Your selection [default 1]: 1

 恩,如果你没有帐号,在这一步选择2吧,我们不二了,分道扬镳鸟,选择1,回车根据提示输入用户名和密码,接着就等待处理。 

Registering somefunctions to http://pypi.python.org/pypi
Server response (200): OK
running sdist
... output trimmed for brevity ...
running upload
Submitting dist\somefunctions.tar.gz to http://pypi.python.org/pypi
Server response (200): OK
I can store your PyPI login so future submissions will be faster.
(the login will be stored in ~/.pypirc)
Save your login (y/N)?n

 当你看到上面这种信息的时候,说明已经完成了上传工作,这个时候你的包就在PyPI上了。

TIPS:

  1. 可能上传的过程出现问题,这个时候你需要终止当前过程,之后到PyPI上查看,如果已经有了这个包,你需要删除(建议操作),或者你重新编译(用新的版本号)在上传
  2. 最后问你要不要保存你的帐号信息,你可以选择y/n,y的话,在你的用户根目录下会有个.pypirc文件,里面有你账户的明文信息。

包到这里,就完成了上传PyPI的工作了。你如果要用,安装下就好:

pip install somefunctions

这个时候,你在你新的项目中只要直接import就可以了

import somefunctions

## Or 

from somefunctions import modulename
到此就结束了,是不是感觉很简单?

 

 后记:

本文是Mitchell Chu根据自己打包的经历写的一篇入门文章,由于本人也是刚刚开始使用,难免会有错谬之处,还请指正。另,文中仅仅是打包成压缩包的形式,还有编译成可执行文件的发布方式这里没有,有此需要的请参考文后的参考文档。

 

参考:

  1. PACKAGING PYTHON LIBRARIES(E文)
  2. PyPI Classifiers(PyPI上Classifiers的详细文档)

reStructuredText链接报重复目标名的编译警告

MitchellChu 2014-09-06 其他技术

在进行的文件编译的时候,有的时候会出现下面的警告信息:

warning: check: Duplicate implicit target name: "license"

编译中出现这个警告是因为.rst文件中包含了两个相同的链接名称,但这两个相同的名称指向的目标地址却不一样导致的。比如下面的这两个:

`我的博客 <http://blog.useasp.net/>`_
'我的博客 <http://blog.useasp.net/default.aspx>`_

这两个相同的文字,指向了不同的地址(虽然访问后是一样的)。在reStructuredText编译的时候就会出现了。

要解决这个问题,其实只需要在后面在加一个下划线,变成下面这样即可:

`我的博客 <http://blog.useasp.net/>`__
'我的博客 <http://blog.useasp.net/default.aspx>`__

.. 希望你已经看到了最后下划线数量的不同了。

  

Emacs中reStructuredText模式(rst-mode)的快捷键

MitchellChu 2014-09-06 其他技术

这篇是前面一篇reStructuredText教程文章的补充,因为本人使用Emacs来编辑rst文件,为了加快编辑速度,需要使用到rst-mode下的快捷键,因此根据文档整理出一份快捷键,方便自己后继查找使用,也希望能够给有需要朋友一些帮助。

快捷键 说明
M-x rst-mode 进入rst-mode。
C-h v rst-version 查看当前rst-mode的版本。如果要查看emacs的版本,后面变成emacs-version即可
C-c C-a *这个开始的是编辑标题用的快捷键前缀,需要配合后面的的按键使用(下同)。
C-c C-c *编译当前文档的前缀快捷键
C-c C-l *列表的快捷键前缀
C-c C-r *操作当前区域的命令的快捷键前缀。
C-c C-t *TOC相关的快捷键前缀。
C-h m 在rst-mode下,这个是列出所有模式的按键绑定列表。
C-c C-a C-a 插入标题
C-c C-= 同上,注意:在Linux的命令行下,Mitchell测试下来无效(Emacs Version =24.3),Win 7下正常。
C-= 同上,注意:在Linux的命令行下,同样无效。不识别C-=这个快捷键,不知道为什么.
C-- C-= 默认Emacs中下的Title是使用上下划线的方式表示。使用这个快捷键可以切换成下划线和上下划线的表示方式。Linux命令行下失效,
C-u C-= 同上功能,Linux命令行失效。
C-u - C-c C-a C-a 功能同上,Linux命令行下有效.
C-c C-a C-s 把当前文档的所有标题的修饰符改成统一(一般是:=-)的表示方式。
C-c C-a C-d 查看标题的层级及其修饰符.
C-M-a rst-backward-section,跳到上一个章节的标题
C-M-e rst-forward-section,跳到下一个章节的标题上
C-M-h rst-mark-section,标记当前章节内容,选中章节内容
M-} forward-paragraph,跳到下一个段落。
M-{ backward-paragraph,跳到上一个段落。
C-c C-r TAB rst-shift-region, 是文本块享有缩进一个TAB的位置。如果之前选中了一个区域,那么在使用的时候,被选中区域内的所有块都会向右缩进一个TAB位置。这个有的时候缩进会错乱,还不知道是什么情况。
M-- C-c C-r TAB 向左移动一个TAB位置。上个命令和这个命令都可以在前面加上M-2或者M-- 2表示是向右还是向左移动的位置数(2为移动两个TAB位置),如果是M-0做前缀,则移除所有的所经。
C-j newline-and-indent,换行并缩进,会根据当前情况进行缩进排版。
M-q fill-paragraph, 填充段落。如果你一个段落被分成好几行,那么当你按下这个的时候,当前段落会重排成一行。
C-c C-l C-e rst-enumerate-region,将当前区域变成有序列表,如果选中区域是多行,并且行之间有空行,则会以空行为界,转换成多个列表项,没空行分隔,则转成一个列表项。
C-c C-l C-b rst-bullet-list-region,将当前区域转成无序列表。原理同上。
C-u C-c C-l C-e/b 如果以这个作为上面两个命令的前缀,则每行都被转成列表项,而不是以空行分隔。
C-c C-l C-s rst-straighten-bullets-region,重排无序列表,规范下* -的分类符用法,使得看起来更清晰些。
C-c C-l C-i rst-insert-list,插入列表。会提示你要使用的编号,如果是有序列表,你输入起始编号之后,后面你再次按下此快捷键,会自动增加编号值。
C-c C-r C-l rst-line-block-region,把当前区域变成line block.就是每行前面加"|",Line Block请参见官方文档。当时文档中说要移除Line Blocks,只要使用一个前缀参数,但不知道如何调用(C-u不见效)。
M-; comment-dwim,将所选区域变成注释。要移除注释符,使用C-u M-;
C-c C-c C-c rst-compile,最常用的命令,它会调用编译命令进行编译,这个过程中它会检视父目录中的docutils.conf文件(有的话),让后添加到命令行选项中。
C-c C-c C-a rst-compile-alt-toolset,使用备选的工具来编译。这个和上面的命令可以通过设置rst-compile-primary-toolset 和 rst-compile-secondary-toolset来改变。
C-c C-c C-x rst-compile-pseudo-region,将当前区域传到rst2pseudoxml.py,并在新的buffer显示效果
C-c C-c C-p rst-compile-pdf-preview,将当前的文档转成PDF,并在结果上加载一个查看器。
C-c C-c C-s rst-compile-slides-preview,将当前文档转成S5 slides并在Web浏览器上预览。
C-c C-t C-t rst-toc,当文档足够长的时候,直接浏览起来并不是很方便,可以用这个来快速跳转。此快捷键在新的buffer里面产生一个根据Title编排的目录(含缩进),在新buffer上,移动到要跳转的Title上,直接回车或者按f键,跳到对应Title的文档位置;按q退出当前新buffer(切换到后端了);按z则完全关闭新buffer。
C-c C-t C-i rst-toc-insert,在光标所在位置为文档插入TOC(Table of Contents),注意,插入的位置必须是第一个Title之后的位置,在文档最前面插入时不会产生任何TOC内容。这点和帮助说明不一致。
C-c C-t C-u rst-toc-update,更新文档中的现存TOC内容。会自动定位到.. contents::指令后的一插入TOC。
C-c C-t C-j rst-goto-section,当光标地在TOC内容上时,此快捷键能快速定位到对应的Section Title上。

 这个下的reStructuredText模式的快捷键对照表中的内容经过Mitchell的测试,由于第一次用,并成文,可能会有些不太清楚的地方,Mitchell在有疑问的地方已经做出了说明。

Emacs下的这个快捷键并不能提供全面的内容输入帮助,比如在需要输入表格或者插入链接的时候,就是没有快捷键可以使用,而插入链接这是多么常用的一个功能啊,没想明白为啥没有这个快捷键。

TIPS:在表中有删除线的快捷键是不能单独使用的,只是其他快捷键的一个前缀。

 

参考文档:

1. Emacs Support for reStructuredText 本文内容来源.

reStructuredText(.rst)语法规则快速入门

MitchellChu 2014-09-05 其他技术

这几天写了个的模块,用Markdown写个个README,传到GitHub,感觉效果还不错,就难抑冲动,打了个包,也想放到PyPI上,结果放上去,发现README变成了源代码。一查,才发现PyPI竟然不支持Markdown格式的README文件,好像支持的README要reStructuredText格式的,对菜鸟的我来说这是个坑啊,好不容易在Emacs下用Markdown用的有点熟路了,结果发现却不被支持。只好重新看看reStructuredText的语法了,因此,也就有了此篇reStructuredText语法快速入门。

先文绉绉的来一段的介绍吧:

reStructuredText是一种轻量级的文本标记语言,直译为:重构建的文本,为Python中Docutils项目的一部分。其一般保存的文件以.rst为后缀。在必要的时候,.rst文件可以被转化成PDF或者HTML格式,也可以有Sphinx转化为LaTex,man等格式,现在被广泛的用于程序的文档撰写。

 好了,时间无多,直接正题:

reStructuredText大致分章节,段落,块和列表这几种内容。而在这其中reStructuredText最主要用得到的标记也就是:

下面一一介绍:

 

 

标题(Title)

来看看标题的实例:

===================
这就是一个标题
===================

----------------
这也是一个章节标题
----------------

怎么样,看起来不难吧,你只要按这个写法,就能被reStructuredText认识,并被解释为章节标题。reStructuredText可用于作为标题修饰的字符有很多很多:

! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~

只要你想,上面的任意一个都可以用来作为标题的修饰符,当然,reStructuredText也是有推荐的,它推荐下面这些字符:

= - ` : . ' " ~ ^ _ * + #

这些字符是上面一堆字符中稍微看起来不会那么奇怪的一部分,当然,个人建议不要那么花哨,尽量用这两个中的一个:

= -

上面实例的写法也许有点复杂,.rst文件中,你还可以只给出下半部分的字符即可:

这个标题和上面的一样
===================

TIPS:作为修饰的字符长度要大于等于文字长度。另外,标题是能够嵌套的。

 

段落(Paragraphs)

段落一般隶属于某个章节中,是一块左对齐并且没有其他元素体标记的块。在.rst文件中,段落和其他内容的分割是靠空行来完成,如果段落相较于其他的段落有缩进,reStructuredText会解析为引用段落,样式上有些不同。

这里是一段reStructuredText的内容,它可以很长很长。。。。最后,末尾留出空行表示是本段落的结束即可。


这里是另外一段reStructuredText的内容,这段内容和上一段之间,乃至后面的其他内容之间都要留出空行进行分割。

    这个也是段落,当时由于缩进了,会变成引用段落。显示和直接的段落有点不同

 

列表(List)

列表在HTML中被分为两种,一个是有序列表(Enumerated Lists),一种是无序列表(Bullet Lists),在reStructuredText中,我们也能找到这两种列表,还有一种称为定义列表(Definition Lists),这和HTML中的DL一样,在.中可以支持嵌套列表。

无序列表要求文本块是以下面这些字符开始,并且后面紧跟空格,而后跟列表项的内容,其中列表项比趋势左对齐并且有与列表对应的缩进。

* + - • ‣ ⁃

还是那句话,用最常用的几个字符就好,不用那么花哨。下面是示例:

- 这里是列表的第一个列表项

- 这是第二个列表项

- 这是第三个列表项

  - 这是缩进的第一个列表项
    注意,这里的缩进要和当前列表项的缩进同步。

- 第一级的第四个列表项

- 列表项之间要用个空格来分割。

有序列表在格式上和无序列表差不多,但是在使用的前缀修饰符上,使用的不是无序列表那种字符,而是可排序的字符,可以识别的有下面这些:

arabic numerals: 1, 2, 3, ... (no upper limit).
uppercase alphabet characters: A, B, C, ..., Z.
lower-case alphabet characters: a, b, c, ..., z.
uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999).
lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999).

如果你不想使用这些,在你标明第一个条目的序号字符后,第二个开始你还可以使用"#"号来让reStructuredText自动生成需要的序号(Docutils >= 0.3.8)。

1. 第一项
    巴拉巴拉好多内容在这里。。。

#. 第二项

    a. 第二项的第一小项

    #. 第二项的第二小项

#. 第三项

 定义列表:每个定义列表项里面包含术语(term),分类器(classifiers,可选), 定义(definition)。术语是一行文字或者短语,分类器跟在术语后面,用“ : ”(空格,冒号,空格)分隔。定义是相对于术语缩进后的一个块。定义中可以包含多个段落或者其他的内容元素。术语和定义之间可以没有空行,但是在定义列表前后必须要有空行的存在。下面是示例:

术语1
    术语1的定义

术语 2
    术语2的定义,这是第一段

    术语2的定义,第二段

术语 3 : 分类器
    术语3的定义


术语 4 : 分类器1 : 分类器2
    术语4的定义

 TIPS:在reStructuredText中,还有两种列表,一种是字段列表(Field Lists),一种是选项列表(Option Lists)。由于是rst的,这里不做深入介绍

 

 表格(Table)

reStructuredText提供两种表格:网格表格(Grid Tables), 简单表格(Simple Tables)。

 网格表中,共使用的符号有:

- = | +
“-” 用来分隔行, “=“ 用来分隔表头和表体行,"|" 用来分隔列,而"+"用来表示行和列相交的节点,如下面的例子:
+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

来自docutils的帮助文档.

 TIPS:表头行是可选的,如果你不需要,就可以不用"="来分割了。

 

简单表格:这种表格比网格表来说简单许多,一般用于简单的数据展示。其用于修饰的字符也仅两个而已:

= -

一般用"="就能完成简单表格的绘制,如果有表头,同样需要用"="将它和表体(body)内容分开,否则会被视为无表头数据。

基本形式
========

`下面这种是最简单的表格形式,当然你也可以去掉表头展示。`

=====  =====  =======
  A      B    A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

表内嵌入
========

`下面这种简单表内有列表`

=====  =====
col 1  col 2
=====  =====
1      Second column of row 1.
2      Second column of row 2.
       Second line of paragraph.
3      - Second column of row 3.

       - Second item in bullet
         list (row 3, column 2).
\      Row 4; column 1 will be empty.
=====  =====

表头合并
========

`表头进行分类合并`

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False A
True   False  True
False  True   True
True   True   True
=====  =====  ======

 TIPS:列需要和"="左对齐,不然可能会导致出错;如果碰到第一列为空时,需要使用"\"来转义,不然会被视为是上一行的延续;网格表和简单表中,简单表比较适合展现简单的数据,这些数据本身不需要太复杂的展现形式,而一旦碰到需要和并单元格这类的复杂操作,可能网格表会更加适合。

表格中还有更复杂的表格形式,比如:CSV表格,列表表格。这些复杂的格式就留给有兴趣的朋友深入吧。

 

块(Blocks)

块在reStructuredText中的表现方式也有好几种,但是最常见的是文字块(Literal Blocks)。这种块的表达非常简单,就是在前面内容结束之后,用两个冒号" :: "(空格[Optional],冒号,冒号)来分割,并在之后紧接着插入空行,而后放入块的内容,块内容要相对之前的内容有缩进。

这里是块之前的的内容。。。::

   这里是块的内容。前面有缩进,空行,和::分隔符。
    此处内容会被一直视为块内容

    空行也不能阻断块内容。。

但是,当内容像这样,不再和块内容一样缩进时,块内容就自动的结束了。

这是块的最简单方式,一般我们编写的代码块就是用这种方式表现(如下), 除此之外,.rst还有引用文字块(Quoted Literal Blocks),行块(Line Blocks),块引用(Block Quotes)等。

下面是我们的测试代码:

::

    for i in [1,2,3,4,5]:
        print i
    # 代码块测试

很简单的代码块测试。

 更多的块内容,请参阅官方帮助文档。

 

样式(Style)

reStructuredText中支持对文本进行样式控制,比如:粗体(Strong),斜体(Italic),等宽字体(Monospace),引用( interpreted text)。

.. Strong Emphasis

This is **Strong Text**. HTML tag is strong.粗体

.. Italic, Emphasis

This is *Emphasis* Text.这个HTML使用em, 斜体

.. Interpreted Text

This is `Interpreted Text`. 注意,这个HTML一般用<cite>表示

.. Inline Literals

This is ``Inline Literals``. HTML tag is <tt>. 等宽字体.

 

来点补充,如果你需要在文档中插入超链接,那么你可以像下面这样:

我这里是一个 链接_.

.. _链接: http://blog.useasp.net

这种方式要求定义链接,而后引用链接。而且链接要有空格分隔前面的文字。这种方式略嫌麻烦,你可以用更加简化的方式——个人比较推荐:

这里同样是一个 `链接<http://blog.useasp.net>`_,不需要特别设置。

TIPS: 我们会发现,两个处理连接的时候,都需要在链接文字前面要空格与前面进行分割,这个在英文当中比较好处理,因为单个词之间有空格,而在中文中,字之间没有空格,如果加入空格,在显示时会有空格,影响观感,为此,如果在中文中使用,需要考虑好。

到此为止,reStructuredText这个的基本用法已经展现完毕,进入实战吧,骚年!

 

参考文献:

1. reStructuredText Markup Specification (本文有些例子是来源于此页面)

2. 在线reStructuredText编辑器,编辑器1编辑器2

关于博主

  一枚成分复杂的网络IT分子,属于互联网行业分类中的杂牌军。