为你的项目添加文档

VuePress

https://vuepress.vuejs.org/zh/

Vue驱动静态网站生成器，非常不错哟,支持Markdown

ReadTheDocs

readthedocs是一个文档托管网站。它可以连接GitHub帮助你编译项目文档。编译好的文档会自动的发布在http://项目名称.readthedocs.io上。

Sphinx

Sphinx 是 readthedocs 网站首推的文档生成工具。它的作用是把rst或者markdown文件编译成html或者pdf。这边使用它的原因是需要用它生成文档脚手架，在本地查看编译后的效果。

安装

Sphinx支持python2.7或3.7。我在本机使用了python3.7的版本。因此使用pip3作为下载器。由于需要用到sphinx_rtd_theme这样的插件，macOS下不建议使用brew install sphinx。

1	pip3 install sphinx sphinx_rtd_theme recommonmark sphinx-markdown-tables

布局

新建文件夹，运行如下：

sphinx-quickstart
欢迎使用 Sphinx 2.1.2 快速配置工具。

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

已选择根路径：.

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

项目名称会出现在文档的许多地方。
> 项目名称: sphinx-example
> 作者名称: alpha
> 项目发行版本 []: v0.1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> 项目语种 [en]: zh_CN


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

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

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

➜ tree
.
├── Makefile
├── build
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

目录结构如上所示。build目录将放置编译后的文件。Makefile用于构建文件。source为源文件目录。source/conf.py为文档编译配置文件。index.rst为首页文件。

配置

conf.py

在第14行之后添加这三行依赖导入。分别是支持readthedocs皮肤、markdown支持和markdown table支持。

# sys.path.insert(0, os.path.abspath('.'))
import sphinx_rtd_theme
import recommonmark
import sphinx_markdown_tables

添加以下支持markdown文件解析.

# -- General configuration ---------------------------------------------------
source_parsers = {
   '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']
extensions = [
        'sphinx_markdown_tables',
]

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'

适配readthedocs

在config.py中添加

1	master_doc = 'index'

在source目录中执行

1	pip3 freeze > requirements.txt

打开requirements.txt文件，并去除不必要的引入，保留需要的依赖：

1
2
3

recommonmark==0.5.0
sphinx-markdown-tables==0.0.9
sphinx-rtd-theme==0.4.3

在文档根目录处添加.readthedocs.yaml文件

version: 2
formats: all
sphinx:
    configuration: source/conf.py

python:
    version: 3.7
    install:
        - requirements: source/requirements.txt