2019-11-19 Python sphinx 编写项目手册

首先点进来的应该都知道 sphinx， 一个 python 支持的项目文档框架， 使用 reStructuredText(.rst)语法规则进行文档编写 语法入门 点击这里，实验环境 python3.7.2 venv：

Xnip2019-11-19_09-21-57.png

• 安装 sphinx

pip install sphinx sphinx-autobuild sphinx_rtd_theme

• 创建文档项目，配置项目信息

(venv) Qinfeis-MacBook-Pro:docs Qinfei$ sphinx-quickstart
欢迎使用 Sphinx 2.0.1 快速配置工具。

请输入接下来各项设置的值（如果方括号中指定了默认值，直接
按回车即可使用默认值）。

已选择根路径：.

布置用于保存 Sphinx 输出的构建目录，有两种选择。
一是在根路径下创建“_build”目录，二是在根路径下创建“source”
和“build”两个独立的目录。
> 独立的源文件和构建目录（y/n） [n]: y

项目名称会出现在文档的许多地方。
> 项目名称: ccc管理系统
> 作者名称: 蜡笔不小新
> 项目发行版本 []: v0.01

如果用英语以外的语言编写文档，你可以在此按语言代码选择语种。
Sphinx 会把内置文本翻译成相应语言的版本。

支持的语言代码列表见：
http://sphinx-doc.org/config.html#confval-language。
> 项目语种 [en]: zh

创建文件 ./source/conf.py。
创建文件 ./source/index.rst。
创建文件 ./Makefile。
创建文件 ./make.bat。

完成：已创建初始目录结构。

你现在可以填写主文档文件 ./source/index.rst 并创建其他文档源文件了。用 Makefile 构建文档，像这样：
 make builder
此处的“builder”是支持的构建器名，比如 html、latex 或 linkcheck。

• 修改 conf.py 文件 （我创建了 src 文件夹，用来放置自己编写的 rst 文档）

import os
import sys
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../src'))

# 换个好看的主题
html_theme = 'sphinx_rtd_theme'

• 编写并链接文档到 index.rst
  编辑index.rst,进行引用文件

.. toctree::
   :maxdepth: 2
   :caption: Contents:

    概述 <src/description>

• 生成 html 文件

make html 

• 发布文档

找个支持静态网页文件的地方放置即可，可选 自建nginx、 oss、 git 的pages 、readthedocs等 == 主要看个人心情和口袋里的cions

如果本来有 markdown 文档，可以使用 pandoc 进行文档转换，由于文档转换不是本文重点，pandoc 的安装这里就不写了

pandoc -s -t rst --toc markdown.md -o index.rst

参考文档：
https://blog.csdn.net/qq_26848099/article/details/83583612
https://segmentfault.com/a/1190000007233355
https://zh-sphinx-doc.readthedocs.io/en/latest/contents.html
https://docs-python2readthedocs.readthedocs.io/en/master/configure-sphinx.html
https://www.sphinx-doc.org/en/1.8/usage/quickstart.html