sphinx+reStructuredText

简介

1  reStructuredText是什么？
reStructuredText是扩展名为.rst的纯文本文件，含义为”重新构建的文本“，是python编程语言的Docutils项目的一部分。.rst文件是一种轻量级标记语言，与html的复杂结构相比，它的设计对人更加友好，被设计为容易阅读和编写的纯文本，并且可以借助Docutils这样的程序进行文档处理，也可以转换为html或pdf等多种格式，或由Sphinx这样的程序转换为man手册等更多格式

2  sphinx是什么？
Sphinx 是一种工具，它允许开发人员以纯文本格式编写文档，以便采用满足不同需求的格式轻松生成输出。它使用 reStructuredText标记语法来提供文档控制，可以将 Sphinx想像成为一种文档框架：它会抽象化比较单调的部分，并提供自动函数来解决一些常见问题，比如突出显示标题索引和特殊代码（在显示代码示例时），以及突出显示适当的语法



环境搭建

1  搭建Python环境
sphinx和reStructuredText是python编程语言的一部分，所以需要先配置好Python环境。
在Python的官方网站下载安装程序按默认选项安装即可，默认安装路径C:\python27
需要注意的是根据你的主机是32位还是64位来选择下载哪个进行安装



2  安装setuptools
setuptools是python的一个增强工具，我们安装模块式常用的easy_install命令就是setuptools中的一个工具；
去官方网站下载ez_setup.py，如下图所示，右击->目标另存为，将ez_setup.py下载到本地

然后将ez_setup.py放到python的安装目录C:\python27，如下图所示


进入dos窗口，执行以下命令安装setuptools
[plain] view plaincopyprint?
cd C:\python27 
C:\python27\python.exe ez_setup.py 



3  安装sphinx
安装完setuptools，我们就是可以只用其中的easy_install命令很简单的安装sphinx模块
进入dos界面，输入以下命令
[plain] view plaincopyprint?
C:\python27\easy_install.exe sphinx 

4  设置环境变量
设置环境变量的作用是让你在输入命令的时候不需要在输入完整的路径，只要输入命令名称即可。
在桌面右击计算机->属性->高级系统设置->环境变量，选择系统变量的path项点击编辑，增加以下两个路径
[plain] view plaincopyprint?
;C:\python27;C:\python27\scripts 


需要注意的是每个路径都是以英文的分号来分割，我们添加了两个路径，在这两个路径之间需要用“;”分开，另外，在第一个路径之前也需要增加一个“;”，与原有的路径进行区分

到此为止，windows下搭建sphinx+reStructuredText的工作就全部完成了。
下一节我们以一个简单的实例来展示它的强大功能

使用实例

首先在桌面建立一个空文件夹sphinx-test，在dos下进入该目录，执行以下命令
[plain] view plaincopyprint?
cd C:\Users\xlzh\Desktop\sphinx-test 
sphinx-quickstart 


运行该命令会提示很多是选项，我们只需要在project Name后写上自己的工程名称，Authors Name后写上作者名称，其他的按默认即可
命令结束后会在sphinx-test目录下生成以下几个文件



我们要编辑的就是其中的index.rst，首先我们先不着急编辑，先看一下默认的效果
进入dos窗口，进入shpinx-test目录，执行以下命令
[plain] view plaincopyprint?
cd C:\Users\xlzh\Desktop\sphinx-test 
make.bat html 


出现上面的效果说明转换html通过，会在该目录_build目录下生成响应的html文件，我们进入目录下的_build/html，使用浏览器打开index.html，查看页面效果



以上显示是默认的页面，现在让我们回过头来用记事本打开index.rst并进行编辑，增加几行代码，展示自己的东西，如下所示



需要注意的是此时的index.rst是ANSI编码的，不支持汉字，需要点击文件->另存为，保存为utf-8格式，覆盖原文件即可
修改完毕，再次运行命令
[plain] view plaincopyprint?
make.bat html 

刷新刚才的页面看下效果吧



OK，剩下的工作就是好好学习reStructuredText语言，然后不断的make.bat html和查看页面进行调试了，注意rst文件编写如果不符合规则，make.bat的时候会提示报错信息，按照报错信息修改对应文件的对应行即可


推荐学习网站：http://jwch.sdut.edu.cn/book/rst.html，这个是reStructuredText的简明教程，这个网站本身也是reStructuredText编写的，我们可以通过点击页面左侧的show source查看右侧窗口的源码，比对源码与页面显示，学习更有效率简介

1  reStructuredText是什么？
reStructuredText是扩展名为.rst的纯文本文件，含义为”重新构建的文本“，是python编程语言的Docutils项目的一部分。.rst文件是一种轻量级标记语言，与html的复杂结构相比，它的设计对人更加友好，被设计为容易阅读和编写的纯文本，并且可以借助Docutils这样的程序进行文档处理，也可以转换为html或pdf等多种格式，或由Sphinx这样的程序转换为man手册等更多格式

2  sphinx是什么？
Sphinx 是一种工具，它允许开发人员以纯文本格式编写文档，以便采用满足不同需求的格式轻松生成输出。它使用 reStructuredText标记语法来提供文档控制，可以将 Sphinx想像成为一种文档框架：它会抽象化比较单调的部分，并提供自动函数来解决一些常见问题，比如突出显示标题索引和特殊代码（在显示代码示例时），以及突出显示适当的语法



环境搭建

1  搭建Python环境
sphinx和reStructuredText是python编程语言的一部分，所以需要先配置好Python环境。
在Python的官方网站下载安装程序按默认选项安装即可，默认安装路径C:\python27
需要注意的是根据你的主机是32位还是64位来选择下载哪个进行安装



2  安装setuptools
setuptools是python的一个增强工具，我们安装模块式常用的easy_install命令就是setuptools中的一个工具；
去官方网站下载ez_setup.py，如下图所示，右击->目标另存为，将ez_setup.py下载到本地

然后将ez_setup.py放到python的安装目录C:\python27，如下图所示


进入dos窗口，执行以下命令安装setuptools
[plain] view plaincopyprint?
cd C:\python27 
C:\python27\python.exe ez_setup.py 



3  安装sphinx
安装完setuptools，我们就是可以只用其中的easy_install命令很简单的安装sphinx模块
进入dos界面，输入以下命令
[plain] view plaincopyprint?
C:\python27\easy_install.exe sphinx 

4  设置环境变量
设置环境变量的作用是让你在输入命令的时候不需要在输入完整的路径，只要输入命令名称即可。
在桌面右击计算机->属性->高级系统设置->环境变量，选择系统变量的path项点击编辑，增加以下两个路径
[plain] view plaincopyprint?
;C:\python27;C:\python27\scripts 


需要注意的是每个路径都是以英文的分号来分割，我们添加了两个路径，在这两个路径之间需要用“;”分开，另外，在第一个路径之前也需要增加一个“;”，与原有的路径进行区分

到此为止，windows下搭建sphinx+reStructuredText的工作就全部完成了。
下一节我们以一个简单的实例来展示它的强大功能

使用实例

首先在桌面建立一个空文件夹sphinx-test，在dos下进入该目录，执行以下命令
[plain] view plaincopyprint?
cd C:\Users\xlzh\Desktop\sphinx-test 
sphinx-quickstart 


运行该命令会提示很多是选项，我们只需要在project Name后写上自己的工程名称，Authors Name后写上作者名称，其他的按默认即可
命令结束后会在sphinx-test目录下生成以下几个文件



我们要编辑的就是其中的index.rst，首先我们先不着急编辑，先看一下默认的效果
进入dos窗口，进入shpinx-test目录，执行以下命令
[plain] view plaincopyprint?
cd C:\Users\xlzh\Desktop\sphinx-test 
make.bat html 


出现上面的效果说明转换html通过，会在该目录_build目录下生成响应的html文件，我们进入目录下的_build/html，使用浏览器打开index.html，查看页面效果



以上显示是默认的页面，现在让我们回过头来用记事本打开index.rst并进行编辑，增加几行代码，展示自己的东西，如下所示



需要注意的是此时的index.rst是ANSI编码的，不支持汉字，需要点击文件->另存为，保存为utf-8格式，覆盖原文件即可
修改完毕，再次运行命令
[plain] view plaincopyprint?
make.bat html