安装
$ 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文件配置进去,重新构建即可。