Wanqing’s 学习资料汇集¶
概述¶
使用之前，不得不说下rst+Sphinx着实很强大呀，看似简单的工具，生成的东西却是一点都不简单，一直以来都对GUI或是WEB太感兴趣，觉得那才是好东西，当接触的结构化文本越来越多的时候，才一点点的发现Python的字符界面下的工具才是传大的！
想形成教程，更多的是想用这些来记录自己所学。人总是趋于将所有事忘掉，自己感觉并不是记忆力超凡的人，反而觉得实在是很普通。接触的东西很多，但却不能形成一个强大的知识系统，真是遗憾！
一天一点，有一些就记录一些，长久坚持下去，我想必对自己产生很强大的作用。知识在于积累，这就是积累的一种方式了。
章节索引¶
读书笔记¶
概述
记录读书时有所得的内容，好读书，却知之的甚少，精读细读的少，而在读的过程中去认真记录过的就更少了。俺在豆瓣上有个读书的列表：
http://book.douban.com/people/wyattwang/
读的过程中，也希望能接和更多的爱书的朋友一起交流。下面则是我在读书时，记录下来的一些东西。
本节目录
《Linux 系统管理技术手册》¶
很厚很大的一本书，字挺小，这样说来内容是很多的，对自己来说还是算挺深的，但看得出，这书确实写得全面。豆瓣地址：
Python¶
收集一些Python学习中的资料，笔记及其它。
Linux¶
记录Linux基础技术，服务器技术，相关的其它技术等。
Linux¶
Ubuntu¶
HTTP 协议¶
http协议详解¶
三、HTTP协议详解之响应篇¶
在接收和解释请求消息后，服务器返回一个HTTP响应消息。
HTTP响应也是由三个部分组成，分别是：状态行、消息报头、响应正文
1、状态行格式如下：
HTTP-Version Status-Code Reason-Phrase CRLF
其中，HTTP-Version表示服务器HTTP协议的版本；Status-Code表示服务器发回的响应状态代码；Reason-Phrase表示状态代码的文本描述。
状态代码有三位数字组成，第一个数字定义了响应的类别，且有五种可能取值：
1xx：指示信息--表示请求已接收，继续处理
2xx：成功--表示请求已被成功接收、理解、接受
3xx：重定向--要完成请求必须进行更进一步的操作
4xx：客户端错误--请求有语法错误或请求无法实现
5xx：服务器端错误--服务器未能实现合法的请求
常见状态代码、状态描述、说明：
200 OK //客户端请求成功
400 Bad Request //客户端请求有语法错误，不能被服务器所理解
401 Unauthorized //请求未经授权，这个状态代码必须和WWW-Authenticate报 //头域一起使用
403 Forbidden //服务器收到请求，但是拒绝提供服务
404 Not Found //请求资源不存在，eg：输入了错误的URL
500 Internal Server Error //服务器发生不可预期的错误
503 Server Unavailable //服务器当前不能处理客户端的请求，一段时间后， //可能恢复正常
eg：HTTP/1.1 200 OK （CRLF）
2、响应报头后述
3、响应正文就是服务器返回的资源的内容
结构化文本¶
reStructuredText¶
概述¶
reStructuredText，重构建文本，是一种优秀的写作工具。
使用格式¶
基本原素¶
字符串元素
连续的字符组成字符串元素。
行元素
下划线（有时包括上划线）和文本构成的元素，例如标题、表格
块元素
具有相同缩进的元素为块元素，例如段落、表格。块元素以 空行 结束，不管多少空行，都视为一行。
页面元素
类似于行元素，但不多含缩进：
标题
============
分隔线
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
章节标题
=====================
_____________________
~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^
"""""""""""""""""""""
等等
注释
注释是以 .. 起始的超级块元素，注释中的内容只在源文件中显示，并不在结果中显示
.. 注释
第二行
第三行
第二段
第六行
新的开始
引导符 .. 前不能有其它字符，之后要有一个空格与注释内容分隔开（ .. 同时是一个字串元素，前后都要有分隔符）
块引用
块引用是以 :: 起始的超级块元素，块引用的内容不作任何处理，以原文显示
块引用 ::
第一行
第二行
第四行
新的开始
引导符 :: 后必须有一个空行
基本格式¶
源码¶
工程组织¶
Sphinx¶
概述¶
Sphinx 是种令人可以轻松撰写出明智/优美的文档工具, 由 Georg Brandl 在BSD 许可证下创造.
Sphinx 已在支持是 the 新版Python 文档的生成, 也成为Python项目首选的文档工具,同时也对 C/C++ 工程有很好的支持; 进一步的,也将对其它开发语言进行特殊支持.
Sphnix还在继续开发. 下列特性工作良好,并在Python官方文档中有“体现”:
- 丰富的输出格式: HTML (包括M$帮助), LaTeX (为PDF输出), manual pages(man), 纯文本
- 完备的交叉引用: 语义化的标签,并对 函式,类,引文,术语以及类似片段消息可以自动化链接
- 明晰的分层结构: 轻松定义文档树,并自动化链接同级/父级/下级文章
- 美观的自动索引: 可自动生成美观的模块索引
- 精确的语法高亮: 基于 Pygments 自动生成语法高亮
- 开放的扩展: 支持代码块的自动测试,自动包含Python 的模块自述文档,等等
- Sphinx 使用新结构化文本 作为标记语言,因而直接享受了来自Docutils 为 reStructuredText 提供的多种工具和能力!
安装¶
解决依赖关系
- Python 2.x (http://www.python.org/), 并将 Python 加入到 Path 中;
- Setup Tools: Python 的一个包安装/管理工具(http://pypi.python.org/pypi/setuptools, win 下有 exe, 直接安装即可);
- 安装 docutils, cmd 下进入 kissyteam/tools/docutils-0.7, 运行 python setup.py install;
安装 Sphinx
- cmd 下运行: easy_install -U Sphinx;
- cmd 下进入 kissyteam/tools/sphinx-to-github, 运行 python setup.py install;
配置¶
使用¶
编译文档
- cmd 进入 kissyteam 目录, 运行 make html (msdos下运行 make.bat html , 在 _build 下生成 html;
- 如果你想进一步了解如何创建 sphinx 工程, 见 http://code.google.com/p/pymotwcn/wiki/SphinxprojectHowto ;
模板修改¶
配置文件为 conf.py ，在其中找到 html_theme = 'default' 这一段，基中“default”即为模板名称。Sphinx提供七种模板候选，名称为别为：
- default
- sphinxdoc
- scrolls
- agogo
- traditional
- nature
- haiku
修改模板，只需将上面提到的 default 换成后面相应的六种名称即可。效果图，请移步这里：
LaTeX¶
参照例子： http://d.ream.at/setup-tex-utf-8-cjk-enviroment-in-ubuntu/
安装¶
安装TexLive+Latex+CJK¶
打开终端，执行下述命令安装TexLive和常用的一些Latex宏包（可以根据自己的需要增改）：:
sudo apt-get install texlive texlive-math-extra texlive-latex-extra texlive-latex-recommended texlive-pictures texlive-science texlive-bibtex-extra latex-beamer
如果硬盘充裕的话，直接完整安装也可以：:
sudo apt-get install texlive-full latex-beamer
安装完后，就可以安装CJK的相关软件包了，如果只需要获得中文支持，那么执行：:
sudo apt-get install latex-cjk-chinese ttf-arphic-* hbf-*
如果硬盘充裕的话，建议安装latex-cjk-all以获取完整支持。
生成中文字体包¶
安装好TexLive+CJK以后，还需要安装一个软件──fontforge用于生成字体：:
sudo apt-get install fontforge
照单全收，全部安装的，下载的有800多M，我自己开始的时候还安装过 fragmaster ，一起加起来，估计有一个G的数据吧，真是太大了。
字体包：
http://code-of-tualatrix.googlecode.com/files/font.tar.bz2
我没有找宋体来，而是把系统里的文泉驿微米黑拿来用的。然后生成字体地图：:
cd ~/font
time fontforge -script subfonts.pe simsun.ttc song Unicode.sfd
电脑正在工作，不知道要多少时间，文章说要二十多分钟。我的时间：:
real 4m36.565s
user 4m33.025s
sys 0m0.924s
字体描述文件，建立一个makemap文件，内容如下：:
for i in *.tfm
do
cat >> song.map << EOF
${i%.tfm} ${i%.tfm} < ${i%.tfm}.pfb
EOF
done
收集的一些关于reStructuredText和Sphinx的资料¶
打算用reStructuredText和Sphinx重组自己平时所收集的一些资料，将其汇总形成一个个人资料库。结构化文件，编辑起来方便，存放也很方便，又能进行版本管理，又能支持多种格式的输出，没道理不喜欢这个。下面交这两天收集到的关于这方面的资料汇总一下。
关于reStructuredText的资料¶
安装ReST¶
当然，使用这个工具，需要python的支持了，所以得有pyhton才行，如果你是在Linux上，比如Ubuntu，那么Python早就安装好了的。
到下面地址下载docutils源码包：
http://docutils.sourceforge.net/index.html
解压后，在其目录执行： python setup.py install
使用easy_install 安装，如果还没安装这个工具的话，得先安装它，在 这里 获得安装程序，然后运行 python ez_setup.py install 。 安装好后，再在终端下执行 easy_install docutils ，即可。
编辑一个文本，名为 test.rst ，内容为：:
Title
==========
哈哈，这里是内容
然后这里是链接： http://google.com
生成HTML，执行命令： `` rst2html test.rst test.html`` [1] ，这里在你的当前目录下，就会自动生成一个 test.html 文件了！
Note
如果没有指定输出的html文件，则只能看到html代码，而不能看到文件。
如果只是编辑一些单个的文件，就使用 rst2html 就够了，详细参数 [2] ：:
rst2html [参数] <源文件.rst> [目标文件.html]
如果不指定目标文件，而输出Html代码，并不生成文件
-r <levle> 设定报告级别，默认为 2
--tab-width=<width> 设定输出的缩进宽度，默认8个空格
--stylesheet-path=<file> 指定CSS文件
--embed-stylesheet 使用嵌入式CSS
--footnote-references=<format> 脚注格式。 barckets方括号 superscript上标
--compact-lists 忽略列表中多余的空行，默认 enabled
--config=<file> 指定配置文件
--footnote-backlinks 允许从脚注跳回原文，默认选项
--toc-top-backlinks 允许从标题跳回索引，默认选项
关于教程¶
reStructuredText简明教程： http://blog.csdn.net/jiyucn/archive/2008/03/07/2157189.aspx
这个应该不是原教程位置，是转发的。如果你英文比较好的话，也可以直接读英文版的快速入门教程：
Quick reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html
关于Sphinx的资料¶
使用Sphinx将结构化文本生成文档，程序员完文档专用工具，特别是Python程序员。
创建Sphinx文档工程¶
创建目录，并使用 sphinx-quickstart 生成程 ([3] [4] )：
mkdir TestProject
cd TestProject/
~/TestProject$ sphinx-quickstart
Welcome to the Sphinx 1.0.1 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Enter the root path for documentation.
> Root path for the documentation [.]: ## 这里也可以不直接指定目录，如果是在已建好的目录中创建项目，则直接回车即可。
## 以下内容，为空的则是采用默认设置，直接回车。
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/N) [n]:
Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:
The project name will occur in several places in the built documentation.
> Project name: TestProject
> Author name(s): wwq
Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1. If you don't need this dual structure,
just set both to the same value.
> Project version: 0.1
> Project release [0.1]:
The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.
> Source file suffix [.rst]:
One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:
Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]: y
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:
> pngmath: include math, rendered as PNG images (y/N) [n]:
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:
> viewcode: include links to the source code of documented Python objects (y/N) [n]:
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]: y
> Create Windows command file? (Y/n) [y]: y
Finished: An initial directory structure has been created.
You should now populate your master file ./index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
操作完后，在你的目录下会生成下面这些目录及文件：
wyatt@wyatt-desktop:~/TestProject$ tree
.
├── _build
├── conf.py
├── index.rst
├── make.bat
├── Makefile
├── _static
└── _templates
在这个目录里面，可能建寻一些目录来存放rst源文件，当然也可以直接在这个目录里创建文件。
生成HTML¶
运行:
make html
运行时的提示：
wyatt@wyatt-desktop:~/TestProject$ make html
sphinx-build -b html -d _build/doctrees . _build/html
Making output directory...
Running Sphinx v1.0.1
loading pickled environment... not yet created
loading intersphinx inventory from http://docs.python.org/objects.inv...
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.
Build finished. The HTML pages are in _build/html.
如提示所说，生成的文件被放在了 -build/html 目录中，进去打开吧：
参考资源索引¶
| [1] | 参考： http://shellexy.info/books/obp.rwpy4learner/html/ch02/WriteDocument.html |
| [2] | 参考： http://blog.csdn.net/jiyucn/archive/2008/03/07/2157189.aspx |
| [3] | 参考： http://shellexy.info/books/obp.rwpy4learner/html/ch02/WriteDocument.html#sphinx |
| [4] | 参考： http://code.google.com/p/pymotwcn/wiki/SphinxprojectHowto |
共享协议¶
本作品采用 知识共享署名-非商业性使用-相同方式共享 2.5 中国大陆许可协议 进行许可。