Sphinx入门和RTD线上配置

安装

$ 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文件如下：

# 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文件配置进去，重新构建即可。