1. SPHINX¶

1.1. 安装 ¶

在Windows上安装Sphinx

如果你的Windows电脑已经安装好了Python或Pip的话，只需要在CMD窗口中执行 pip install Sphinx。

1.1.1. 更改皮肤conf.py ¶

#html_theme = 'alabaster'

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

1.2. 构建 ¶

sphinx-quickstart

make html

cd _build/html
python -m SimpleHTTPServer 8000

1.3. 自动构建 ¶

1.3.1. sphinx-autobuild ¶

pip install sphinx-autobuild

sphinx-autobuild . _build/html \
    -p 8000 -H 172.17.0.4 \
    --ignore "*.swp" --ignore "*.pdf" --ignore "*.log" --ignore "*.out" --ignore "*.toc" \
    --ignore "*.aux" --ignore "*.idx" --ignore "*.ind" --ignore "*.ilg" --ignore "*.tex"

1.3.2. 参数说明 ¶

-p --port option to specify the port on which the documentation shall be served (default 8000)
-H --host option to specify the host on which the documentation shall be served (default 127.0.0.1)
-i --ignore multiple allowed, option to specify file ignore glob expression when watching changes, for example: *.tmp
-B --open-browser automatically open a web browser with the URL for this document
--no-initial disable initial build
-s --delay delay in seconds before opening browser if –open-browser was selected (default 5)
-z --watch multiple allowed, option to specify additional directories to watch, for example: some/extra/dir

1.3.3. Makefile integration ¶

To integrate the sphinx-autobuild command in the Makefile generated by Sphinx, add the following target:

livehtml:
    sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

Then run with: make livehtml

1.4. Sphinx 使用手册 ¶

1.5. 创建、托管和浏览文档 ¶

Read the Docs

1.6. 上传到GitHub ¶

1.6.1. master分支 ¶

# edit .gitignore to ignore _build
echo "_build" >> .gitignore
git add .gitignore
git commit -m 'ignoring _build'

# create a new directory (in doc/)
mkdir -p _build/html

# clone the entire repo into this directory (yes, this duplicates it)
git clone git@github.com:username/project.git _build/html

1.6.2. gh-pages分支 ¶

# set this directory to track gh-pages
git symbolic-ref HEAD refs/heads/gh-pages
rm .git/index
git clean -fdx

1.6.3. 首次gh-pages分支提交 ¶

# in docs/, run `make html` to generate our doc, which will fill
# _build/html, but not overwrite the .git directory
cd ../..
make html

# now, add these bad-boys to the gh-pages repo, along with .nojekyll:
cd _build/html
touch .nojekyll
git add .
git commit -m 'first docs to gh-pages'
git push origin gh-pages

# [optional] cleanup stuff in duplicate master (in docs/_build/html)
git checkout master
rm .git/index
git clean -fdx

1.6.4. 日常文档修改提交 ¶

# now, when you run `make html` and need to update your documentation,
# you can do it "normally" without worrying about the many vagaries of
# submodule syncing (I can never get the order correct).  just make
# changes, then:
make html
cd _build/html
git commit -a -m 'made some changes, yo'
git push origin gh-pages

1.7. reStructuredText 语法简介 ¶

1.7.1. 内联标记 ¶

星号: text 是强调 (斜体),

双星号: text 重点强调 (加粗),

反引号: text 代码样式.

1.7.2. 列表 ¶

开头放置一个星号和一个缩进. 编号的列表也可以使用符号 # 自动加序号:

这是一个项目符号列表.
它有两项，第二项使用两行.
1. 这是个有序列表.
2. 也有两项.
3. 是个有序列表.
4. 也有两项.你晚点

1.7.3. 表格 ¶

简单表格

A B A and B

False False False

True False False

False True False

True True True
网格表格

Header row, column 1 (header rows optional) Header 2 Header 3 Header 4

body row 1, column 1 column 2 column 3 column 4

body row 2 ... ...

1.7.4. 超链接 ¶

外部链接

使用 a 可以插入网页链接. 链接文本是网址，则不需要特别标记，分析器会自动发现文本里的链接或邮件地址.

段落里包含 a.

1.7.5. 标签链接 ¶

标签链接

1.7.6. 章节 ¶

章节的标题在双上划线符号之间（或为下划线）
- # 及上划线表示部分
- * 及上划线表示章节
- =, 小章节
- -, 子章节
- ^, 子章节的子章节
- ”, 段落

1.7.7. 代码 ¶

语法高亮

.. literalinclude:: ..\conf.py
   :lines: 125-129
   :linenos:

结果

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

Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1	column 2	column 3	column 4
body row 2	...	...