听说reStructuredText不错

看了一位大牛写的文章

http://yuanboshe.github.io/blog/2013-10-select_personal_websit_solution.html



深有感触，感觉自己编辑文档和写博客的能力需要质变啊。

于是找了下这个rST，结果发现不知道怎么装。

（1）

官网这里 http://docutils.sourceforge.net/rst.html

有文档，但是不知道怎么用。

（2）有个在线测试用的

http://www.tele3.cz/jbar/rest/rest.html

还是很好用过的。

================

rst2s5幻灯片演示

================



------------

这里是副标题

------------



为什么要选择reStructuredText

----------------------------

文档格式众多，为什么要选择reStructuredText呢？



* 纯文本，简易的标记语言

* 易学、易用

* 工具链完善，可以轻松转换到HTML，PDF，S5 Slide，TeX等格式



嵌入图片

--------

嵌入图片的效果是什么样的呢？



.. image:: funny.jpg

变成html就是这样的：



（3） 说明书

http://docutils.sourceforge.net/docs/user/rst/quickref.html

（4） 这里也有个教程

http://wiki.jerrypeng.me/rest-tjlug/index.html

root@Ubuntu32:/home/zhangbin# sudo apt-get install python-docutils

Reading package lists... Done

Building dependency tree

Reading state information... Done

The following extra packages will be installed:

docutils-common docutils-doc python-lxml python-pygments python-roman

Suggested packages:

texlive-latex-recommended texlive-latex-base texlive-lang-french

ttf-linux-libertine python-lxml-dbg ttf-bitstream-vera

The following NEW packages will be installed:

docutils-common docutils-doc python-docutils python-lxml python-pygments

python-roman

0 upgraded, 6 newly installed, 0 to remove and 0 not upgraded.

Need to get 2,804 kB of archives.

After this operation, 10.7 MB of additional disk space will be used.

Do you want to continue [Y/n]? y

Get:1 http://us.archive.ubuntu.com/ubuntu/ precise/main docutils-common all 0.8.1-4ubuntu1 [153 kB]

Get:2 http://us.archive.ubuntu.com/ubuntu/ precise/main docutils-doc all 0.8.1-4ubuntu1 [1,289 kB]

Get:3 http://us.archive.ubuntu.com/ubuntu/ precise/main python-roman all 0.8.1-4ubuntu1 [12.6 kB]

Get:4 http://us.archive.ubuntu.com/ubuntu/ precise/main python-docutils all 0.8.1-4ubuntu1 [382 kB]

Get:5 http://us.archive.ubuntu.com/ubuntu/ precise/main python-lxml i386 2.3.2-1 [614 kB]

Get:6 http://us.archive.ubuntu.com/ubuntu/ precise/main python-pygments all 1.4+dfsg-2 [353 kB]

Fetched 2,804 kB in 4s (649 kB/s)

Selecting previously unselected package docutils-common.

(Reading database ... 450000 files and directories currently installed.)

Unpacking docutils-common (from .../docutils-common_0.8.1-4ubuntu1_all.deb) ...

Selecting previously unselected package docutils-doc.

Unpacking docutils-doc (from .../docutils-doc_0.8.1-4ubuntu1_all.deb) ...

Selecting previously unselected package python-roman.

Unpacking python-roman (from .../python-roman_0.8.1-4ubuntu1_all.deb) ...

Selecting previously unselected package python-docutils.

Unpacking python-docutils (from .../python-docutils_0.8.1-4ubuntu1_all.deb) ...

Selecting previously unselected package python-lxml.

Unpacking python-lxml (from .../python-lxml_2.3.2-1_i386.deb) ...

Selecting previously unselected package python-pygments.

Unpacking python-pygments (from .../python-pygments_1.4+dfsg-2_all.deb) ...

Processing triggers for man-db ...

Processing triggers for doc-base ...

Processing 1 added doc-base file...

Setting up docutils-common (0.8.1-4ubuntu1) ...

Setting up docutils-doc (0.8.1-4ubuntu1) ...

Setting up python-roman (0.8.1-4ubuntu1) ...

Setting up python-docutils (0.8.1-4ubuntu1) ...

update-alternatives: using /usr/share/docutils/scripts/python2/rst-buildhtml to provide /usr/bin/rst-buildhtml (rst-buildhtml) in auto mode.

update-alternatives: using /usr/share/docutils/scripts/python2/rst2html to provide /usr/bin/rst2html (rst2html) in auto mode.

update-alternatives: using /usr/share/docutils/scripts/python2/rst2latex to provide /usr/bin/rst2latex (rst2latex) in auto mode.

update-alternatives: using /usr/share/docutils/scripts/python2/rst2man to provide /usr/bin/rst2man (rst2man) in auto mode.

update-alternatives: using /usr/share/docutils/scripts/python2/rst2odt to provide /usr/bin/rst2odt (rst2odt) in auto mode.

update-alternatives: using /usr/share/docutils/scripts/python2/rst2odt_prepstyles to provide /usr/bin/rst2odt_prepstyles (rst2odt_prepstyles) in auto mode.

update-alternatives: using /usr/share/docutils/scripts/python2/rst2pseudoxml to provide /usr/bin/rst2pseudoxml (rst2pseudoxml) in auto mode.

update-alternatives: using /usr/share/docutils/scripts/python2/rst2s5 to provide /usr/bin/rst2s5 (rst2s5) in auto mode.

update-alternatives: using /usr/share/docutils/scripts/python2/rst2xetex to provide /usr/bin/rst2xetex (rst2xetex) in auto mode.

update-alternatives: using /usr/share/docutils/scripts/python2/rst2xml to provide /usr/bin/rst2xml (rst2xml) in auto mode.

update-alternatives: using /usr/share/docutils/scripts/python2/rstpep2html to provide /usr/bin/rstpep2html (rstpep2html) in auto mode.

Setting up python-lxml (2.3.2-1) ...

Setting up python-pygments (1.4+dfsg-2) ...

root@Ubuntu32:/home/zhangbin#

（5）有人说，用easy_insall，不过貌似要装ffmpeg的那些，我担心会引起我系统内部的各种ffmpeg库的混乱。

https://groups.google.com/forum/#!topic/pythontw/AzqXUMPZjNU

所以就没有用这种方式了。

root@Ubuntu32:/home/zhangbin# sudo apt-get install python-setuptools python-vtk python-dev python-qt4

Reading package lists... Done

Building dependency tree

Reading state information... Done

python-dev is already the newest version.

The following extra packages will be installed:

libavcodec53 libavformat53 libavutil51 libgfortran3 libgl2ps0

libhdf5-serial-1.8.4 libibverbs1 libmysqlclient18 libnetcdf6 libnuma1

libopenmpi1.3 libpq5 libqt4-help libqt4-scripttools libqt4-test

libqtassistantclient4 libswscale2 libtorque2 libvtk5.8 mysql-common

python-sip tcl-vtk tcl8.5 tk8.5

Suggested packages:

openmpi-bin lam-runtime libvtk5-dev vtk-examples vtk-doc python-qt4-dbg

mayavi2 tclreadline

The following NEW packages will be installed:

libavcodec53 libavformat53 libavutil51 libgfortran3 libgl2ps0

libhdf5-serial-1.8.4 libibverbs1 libmysqlclient18 libnetcdf6 libnuma1

libopenmpi1.3 libpq5 libqt4-help libqt4-scripttools libqt4-test

libqtassistantclient4 libswscale2 libtorque2 libvtk5.8 mysql-common

python-qt4 python-setuptools python-sip python-vtk tcl-vtk tcl8.5 tk8.5

0 upgraded, 27 newly installed, 0 to remove and 0 not upgraded.

Need to get 43.9 MB of archives.

After this operation, 147 MB of additional disk space will be used.

Do you want to continue [Y/n]? n

Abort.

root@Ubuntu32:/home/zhangbin# apt-get install python-sphinx

Reading package lists... Done

Building dependency tree

Reading state information... Done

The following extra packages will be installed:

libjs-sphinxdoc libjs-underscore python-jinja2 sphinx-common sphinx-doc

Suggested packages:

javascript-common python-jinja2-doc jsmath libjs-mathjax

texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended

The following NEW packages will be installed:

libjs-sphinxdoc libjs-underscore python-jinja2 python-sphinx sphinx-common

sphinx-doc

0 upgraded, 6 newly installed, 0 to remove and 0 not upgraded.

Need to get 1,805 kB of archives.

After this operation, 6,227 kB of additional disk space will be used.

Do you want to continue [Y/n]? y

Get:1 http://us.archive.ubuntu.com/ubuntu/ precise/main libjs-underscore all 1.1.6-1ubuntu2 [31.3 kB]

Get:2 http://us.archive.ubuntu.com/ubuntu/ precise-updates/main libjs-sphinxdoc all 1.1.3+dfsg-2ubuntu2.1 [45.1 kB]

Get:3 http://us.archive.ubuntu.com/ubuntu/ precise/main python-jinja2 i386 2.6-1 [158 kB]

Get:4 http://us.archive.ubuntu.com/ubuntu/ precise-updates/main sphinx-common all 1.1.3+dfsg-2ubuntu2.1 [412 kB]

Get:5 http://us.archive.ubuntu.com/ubuntu/ precise-updates/main python-sphinx all 1.1.3+dfsg-2ubuntu2.1 [312 kB]

Get:6 http://us.archive.ubuntu.com/ubuntu/ precise-updates/main sphinx-doc all 1.1.3+dfsg-2ubuntu2.1 [847 kB]

Fetched 1,805 kB in 7s (227 kB/s)

Selecting previously unselected package libjs-underscore.

(Reading database ... 450838 files and directories currently installed.)

Unpacking libjs-underscore (from .../libjs-underscore_1.1.6-1ubuntu2_all.deb) ...

Selecting previously unselected package libjs-sphinxdoc.

Unpacking libjs-sphinxdoc (from .../libjs-sphinxdoc_1.1.3+dfsg-2ubuntu2.1_all.deb) ...

Selecting previously unselected package python-jinja2.

Unpacking python-jinja2 (from .../python-jinja2_2.6-1_i386.deb) ...

Selecting previously unselected package sphinx-common.

Unpacking sphinx-common (from .../sphinx-common_1.1.3+dfsg-2ubuntu2.1_all.deb) ...

Selecting previously unselected package python-sphinx.

Unpacking python-sphinx (from .../python-sphinx_1.1.3+dfsg-2ubuntu2.1_all.deb) ...

Selecting previously unselected package sphinx-doc.

Unpacking sphinx-doc (from .../sphinx-doc_1.1.3+dfsg-2ubuntu2.1_all.deb) ...

Processing triggers for man-db ...

Processing triggers for doc-base ...

Processing 1 added doc-base file...

Setting up libjs-underscore (1.1.6-1ubuntu2) ...

Setting up libjs-sphinxdoc (1.1.3+dfsg-2ubuntu2.1) ...

Setting up python-jinja2 (2.6-1) ...

Setting up sphinx-common (1.1.3+dfsg-2ubuntu2.1) ...

Setting up python-sphinx (1.1.3+dfsg-2ubuntu2.1) ...

Setting up sphinx-doc (1.1.3+dfsg-2ubuntu2.1) ...

root@Ubuntu32:/home/zhangbin#

（6）用sphinx

=================================================================

参考http://blog.csdn.net/foudary/article/details/9025341

用sphnix的方法来做rST的编辑器，

root@Ubuntu32:/home/zhangbin/Documents# mkdir mydoc

root@Ubuntu32:/home/zhangbin/Documents# cd mydoc

root@Ubuntu32:/home/zhangbin/Documents/mydoc# sphinx-start

sphinx-start: command not found

也确实是一路enter用默认的啊，

root@Ubuntu32:/home/zhangbin/Documents/mydoc# sphinx-quickstart

Welcome to the Sphinx 1.1.3 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)
:

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: test_rst

> Author name(s): zhangbin

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)
:

Please indicate if you want to use one of the following Sphinx extensions:

> autodoc: automatically insert docstrings from modules (y/N)
:

> doctest: automatically test code snippets in doctest blocks (y/N)
:

> intersphinx: link between Sphinx documentation of different projects (y/N)
:

> todo: write "todo" entries that can be shown or hidden on build (y/N)
:

> coverage: checks for documentation coverage (y/N)
:

> pngmath: include math, rendered as PNG images (y/N)
:

> mathjax: include math, rendered in the browser by MathJax (y/N)
:

> ifconfig: conditional inclusion of content based on config values (y/N)
:

> viewcode: include links to the source code of documented Python objects (y/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]:

> Create Windows command file? (Y/n) [y]:

Creating file ./conf.py.

Creating file ./index.rst.

Creating file ./Makefile.

Creating file ./make.bat.

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.

root@Ubuntu32:/home/zhangbin/Documents/mydoc# tree

.

├── _build

│ ├── doctrees

│ │ ├── environment.pickle

│ │ └── index.doctree

│ └── html

│ ├── genindex.html

│ ├── index.html

│ ├── objects.inv

│ ├── search.html

│ ├── searchindex.js

│ ├── _sources

│ │ └── index.txt

│ └── _static

│ ├── ajax-loader.gif

│ ├── basic.css

│ ├── comment-bright.png

│ ├── comment-close.png

│ ├── comment.png

│ ├── default.css

│ ├── doctools.js

│ ├── down.png

│ ├── down-pressed.png

│ ├── file.png

│ ├── jquery.js

│ ├── minus.png

│ ├── plus.png

│ ├── pygments.css

│ ├── searchtools.js

│ ├── sidebar.js

│ ├── underscore.js

│ ├── up.png

│ ├── up-pressed.png

│ └── websupport.js

├── conf.py

├── index.rst

├── make.bat

├── Makefile

├── _static

├── _templates

root@Ubuntu32:/home/zhangbin/Documents/mydoc#

还 生成了makefile啊：



make html

就可以得到一个html：



打开看是这样的：



（7）直接写rst文件转为html

root@Ubuntu32:/home/zhangbin/Documents/mydoc# rst2html

^CTraceback (most recent call last):

File "/usr/bin/rst2html", line 23, in <module>

publish_cmdline(writer_name='html', description=description)

File "/usr/lib/python2.7/dist-packages/docutils/core.py", line 339, in publish_cmdline

config_section=config_section, enable_exit_status=enable_exit_status)

File "/usr/lib/python2.7/dist-packages/docutils/core.py", line 211, in publish

self.settings)

File "/usr/lib/python2.7/dist-packages/docutils/readers/__init__.py", line 68, in read

self.input = self.source.read()

File "/usr/lib/python2.7/dist-packages/docutils/io.py", line 254, in read

data = self.source.read()

KeyboardInterrupt

root@Ubuntu32:/home/zhangbin/Documents/mydoc#

编辑一个文本，名为 test.rst ，内容为：:

Title

==========

哈哈，这里是内容

然后这里是链接： http://google.com


root@Ubuntu32:/home/zhangbin/Documents/mydoc# mkdir test

root@Ubuntu32:/home/zhangbin/Documents/mydoc# cd test

root@Ubuntu32:/home/zhangbin/Documents/mydoc/test# gedit test.rst

忘记加生成的html文件名了。

root@Ubuntu32:/home/zhangbin/Documents/mydoc/test# rst2html test.rst

<?xml version="1.0" encoding="utf-8" ?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />

<title>Title</title>

<style type="text/css">

/*

:Author: David Goodger (goodger@python.org)

:Id: $Id: html4css1.css 7056 2011-06-17 10:50:48Z milde $

:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to

customize this style sheet.

*/

/* used to remove borders from tables and images */

.borderless, table.borderless td, table.borderless th {

border: 0 }

table.borderless td, table.borderless th {

/* Override padding for "table.docutils td" with "! important".

The right padding separates the table cells. */

padding: 0 0.5em 0 0 ! important }

.first {

/* Override more specific margin styles with "! important". */

margin-top: 0 ! important }

.last, .with-subtitle {

margin-bottom: 0 ! important }

.hidden {

display: none }

a.toc-backref {

text-decoration: none ;

color: black }

blockquote.epigraph {

margin: 2em 5em ; }

dl.docutils dd {

margin-bottom: 0.5em }

object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {

overflow: hidden;

}

/* Uncomment (and remove this text!) to get bold-faced definition list terms

dl.docutils dt {

font-weight: bold }

*/

div.abstract {

margin: 2em 5em }

div.abstract p.topic-title {

font-weight: bold ;

text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,

div.hint, div.important, div.note, div.tip, div.warning {

margin: 2em ;

border: medium outset ;

padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,

div.important p.admonition-title, div.note p.admonition-title,

div.tip p.admonition-title {

font-weight: bold ;

font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,

div.danger p.admonition-title, div.error p.admonition-title,

div.warning p.admonition-title {

color: red ;

font-weight: bold ;

font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in

compound paragraphs.

div.compound .compound-first, div.compound .compound-middle {

margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {

margin-top: 0.5em }

*/

div.dedication {

margin: 2em 5em ;

text-align: center ;

font-style: italic }

div.dedication p.topic-title {

font-weight: bold ;

font-style: normal }

div.figure {

margin-left: 2em ;

margin-right: 2em }

div.footer, div.header {

clear: both;

font-size: smaller }

div.line-block {

display: block ;

margin-top: 1em ;

margin-bottom: 1em }

div.line-block div.line-block {

margin-top: 0 ;

margin-bottom: 0 ;

margin-left: 1.5em }

div.sidebar {

margin: 0 0 0.5em 1em ;

border: medium outset ;

padding: 1em ;

background-color: #ffffee ;

width: 40% ;

float: right ;

clear: right }

div.sidebar p.rubric {

font-family: sans-serif ;

font-size: medium }

div.system-messages {

margin: 5em }

div.system-messages h1 {

color: red }

div.system-message {

border: medium outset ;

padding: 1em }

div.system-message p.system-message-title {

color: red ;

font-weight: bold }

div.topic {

margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,

h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {

margin-top: 0.4em }

h1.title {

text-align: center }

h2.subtitle {

text-align: center }

hr.docutils {

width: 75% }

img.align-left, .figure.align-left, object.align-left {

clear: left ;

float: left ;

margin-right: 1em }

img.align-right, .figure.align-right, object.align-right {

clear: right ;

float: right ;

margin-left: 1em }

img.align-center, .figure.align-center, object.align-center {

display: block;

margin-left: auto;

margin-right: auto;

}

.align-left {

text-align: left }

.align-center {

clear: both ;

text-align: center }

.align-right {

text-align: right }

/* reset inner alignment in figures */

div.align-right {

text-align: inherit }

/* div.align-center * { */

/* text-align: left } */

ol.simple, ul.simple {

margin-bottom: 1em }

ol.arabic {

list-style: decimal }

ol.loweralpha {

list-style: lower-alpha }

ol.upperalpha {

list-style: upper-alpha }

ol.lowerroman {

list-style: lower-roman }

ol.upperroman {

list-style: upper-roman }

p.attribution {

text-align: right ;

margin-left: 50% }

p.caption {

font-style: italic }

p.credits {

font-style: italic ;

font-size: smaller }

p.label {

white-space: nowrap }

p.rubric {

font-weight: bold ;

font-size: larger ;

color: maroon ;

text-align: center }

p.sidebar-title {

font-family: sans-serif ;

font-weight: bold ;

font-size: larger }

p.sidebar-subtitle {

font-family: sans-serif ;

font-weight: bold }

p.topic-title {

font-weight: bold }

pre.address {

margin-bottom: 0 ;

margin-top: 0 ;

font: inherit }

pre.literal-block, pre.doctest-block, pre.math {

margin-left: 2em ;

margin-right: 2em }

span.classifier {

font-family: sans-serif ;

font-style: oblique }

span.classifier-delimiter {

font-family: sans-serif ;

font-weight: bold }

span.interpreted {

font-family: sans-serif }

span.option {

white-space: nowrap }

span.pre {

white-space: pre }

span.problematic {

color: red }

span.section-subtitle {

/* font-size relative to parent (h1..h6 element) */

font-size: 80% }

table.citation {

border-left: solid 1px gray;

margin-left: 1px }

table.docinfo {

margin: 2em 4em }

table.docutils {

margin-top: 0.5em ;

margin-bottom: 0.5em }

table.footnote {

border-left: solid 1px black;

margin-left: 1px }

table.docutils td, table.docutils th,

table.docinfo td, table.docinfo th {

padding-left: 0.5em ;

padding-right: 0.5em ;

vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {

font-weight: bold ;

text-align: left ;

white-space: nowrap ;

padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,

h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {

font-size: 100% }

ul.auto-toc {

list-style-type: none }

</style>

</head>

<body>

<div class="document" id="title">

<h1 class="title">Title</h1>

<p>哈哈，这里是内容

然后这里是链接： <a class="reference external" href="http://google.com">http://google.com</a></p>

</div>

</body>

</html>

root@Ubuntu32:/home/zhangbin/Documents/mydoc/test#



参考https://wyatts-docs.readthedocs.org/en/latest/text/rst_sphinx/

这里还有个大牛写的笔记，更全面

http://qixinglu.com/post/note_tools_restructuredtext_sphinx.html