使用 Read The Docs 构建文档

说明以及原理 使用的是git（推荐码云）托管，Read The Docs只是一个构建显示美化的作用

搭建环境

# 需要安装python以及pip
# 安装软件，下载估计有点久
pip install sphinx

开始使用

# 进入搭建文档的目录
mkdir doc
cd doc
# 运行，设置向导
# 安装之后寻找到这个命令的位置，绝对执行，如：/home/lxx/.local/bin/sphinx-quickstart
sphinx-quickstart
# This quick start will walk you through creating the basic configuration; in most cases, you can just accept the defaults. When it’s done, you’ll have an index.rst, a conf.py and some other files. Add these to revision control.
# 打包文档
# meke 调用 sphinx-build，/home/lxx/.local/bin 要放到全局可执行
make html
make pdf
# 或者直接打包
/home/lxx/.local/bin/sphinx-build -b html ./ ./_build

增加 Markdown (不支持Sphinx的许多功能，如内联标记和指令)

# 安装
pip install recommonmark
# 配置 conf.py
from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

参考

# 个人推荐配置
# /home/lxx/Desktop/doc/index.rst
.. toctree::
   :maxdepth: 3
   :caption: 内容:

   README
   docs/备注
# docs/备注.md
# 每一个md文件只有一个#大标题
# 然后依次递增
# 不要嵌套>符号，造成间距太大