## 安装
```
$ brew install sphinx-doc
```
## 启动
```
$ sphinx-quickstart
```
## 配置
> Separate source and build directories (y/n) [n]: n
>
> Project name: my-first-sphinx-project
>
> Author name(s): vincentlu
>
> Project release []: 1.0
>
> Project language [en]: en
初始化后，文件目录如下：
.
├── Makefile
├── _build
├── _static
├── _templates
├── conf.py
├── index.rst
└── make.bat
### 文件作用
_build: 编译好后的文件在这里
_static: 静态配置，如全局图片等
_conf.py: 配置文件
index.rst: 主入口文件
## 开始编辑
接下来，我们可以在这个项目中进行编辑 ，一般，在docs文件夹中建立目录并存放文件。
.
├── auth
│ ├── forgetpassword.md
│ ├── index.rst
│ ├── login.md
│ └── signup.md
├── introduction.md
└── trade
例如在我的doc中，建立了两个文件夹，auth和trade，表示两个模块，在每一个模块中，又有几个文件，分别表示模块中多个子模块。
必须注意的是，不管我们在doc中用怎么样的层级结构来表达，我们必须在主入口（根目录的 index.dst）文件中加载我们已经存放在doc中的文件。例如
.. toctree::
:hidden:
:maxdepth: 1
docs/introduction.md
docs/auth/index.rst
## 开始编译
```
$ make html
```
当编译结束，结果会呈现在_build中
## GO
运行_build中的html文件，即可显示
## 高阶用法
在实际生活中，除了给自己看，还需要和团队一起分享，那么如何把写好的文档分享出去呢？
READTHEDOCS很好的解决了这个问题
实际上，RTD是一个基于SPINX的online工具，很好的把本地要做的东西同步到了线上。
### 准备步骤
1）在READTHEDOCS上注册账号
2）IMPORT一个项目（注意，免费的账号只能import开源库，无法import私有库）
3）点击构建版本构建成功后，即可浏览
### 需要注意的问题
1） 在markdown中，除了文字，还会有时序图和流程图，在这种情况下，不管在本地或者在RTD中，都有可能显示不出来。我列出了这些常用的组件，本地可以pip install一下，在远端，可以把一下依赖放在requirements.txt文件中。然后新建一个yml文件，进行配置。
我的yml文件如下：
```python
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: conf.py
# Build documentation with MkDocs
#mkdocs:
# configuration: mkdocs.yml
# Optionally build your docs in additional formats such as PDF and ePub
formats: all
# Optionally set the version of Python and requirements required to build your docs
python:
version: 3.7
install:
- python --version
- pip install -r requirements.txt
- make html
```
根目录requirements.txt文件内容如下
docutils == 0.12
sphinx == 1.7.9
sphinx-rtd-theme
sphinx-copybutton == 0.2.6
sphinx-version-warning
sphinx-markdown-tables
sphinxcontrib-mermaid > 0.3
recommonmark > 0.4.0
sphinx-notfound-page == 0.1
commonmarkextensions == 0.0.5
commonmark == 0.8.1
git-lfs
在线上环境中，点击高级设置——所需求的文件，把该yml文件配置进去，重新构建即可。
