1. sphinx的安装与使用¶

1.1. 安装sphinx¶

sphinx官方安装说明： http://www.sphinx-doc.org/en/master/usage/installation.html

readthedoc官方说明： https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html

总的来说步骤如下：

安装python3
通过python3安装sphinx包
根据项目要求安装项目的requirements.txt里的软件包

1.1.1. 安装python3¶

windows直接到python官网下载安装

Ubuntu下使用如下指令安装：

sudo apt install python3

1.1.2. 安装sphinx¶

windows下使用如下指令安装：

py -3 -m pip install sphinx
#国内用户推荐使用清华源安装，使用-i指定源
py -3 -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx

Ubuntu下使用如下指令安装

python3 -m pip install sphinx
#国内用户推荐使用清华源安装，使用-i指定源
python3 -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx

#Ubuntu下可能还需要安装如下软件包
apt-get install python3-sphinx

1.2. 使用模板创建sphinx文档¶

本项目的sphinx已适配好支持markdown、默认的readthedoc主题等内容。

如果是要编写新的书籍，推荐直接使用本项目文档作为模版，修改conf.py文件的配置即可改变项目的名字、主题之类的内容。

1.2.1. 下载项目源码¶

先从github下载本项目源代码：

git clone git@github.com:Embdefire/ebf_contribute_guide.git

下载完成后，可看到本项目的结构大致如下：

├── README                    说明文档或软链接至documentation中的说明，方便github阅读
├── base_code                 配套代码
└── documentation             配套文档
    ├── faq                   存储常见问题的文档
    ├── about_us.rst          关于我们
    ├── _build                文档编译输出目录
    ├── conf.py               sphinx配置文件
    ├── contribute            如何参与项目，贡献与投稿的说明
    ├── foreword.rst          前言
    ├── index.rst             目录
    ├── make.bat
    ├── Makefile
    ├── media                 文档中使用的图片文件
    ├── requirements.txt      文档的python依赖
    ├── _static
    ├── _templates
    ├── TODO.rst              待完成的内容，发布的任务列表

特别内容说明如下：

base_code ：该目录通常存放项目的代码，
documentation ：该目录通常存放项目的文档内容，如我们的rst、markdown文档。

1.2.2. 安装python依赖包¶

使用时，要先根据项目的 documentation/requirements.txt 安装依赖的python包。

#切换至requirements.txt文件的同级目录
cd documentation

#requirements.txt文件的同级目录下执行后面的命令

#Windows指令，推荐使用powershell运行
py -3 -m pip install -r requirements.txt
#Ubuntu指令
python3 -m pip install -r  requirements.txt

#国内用户推荐使用清华源安装
#Windows指令，推荐使用powershell运行
py -3 -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
#Ubuntu指令
python3 -m pip install -r  requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

1.2.3. 编写文档¶

安装好后，在项目的文档目录中添加rst或markdown文件即可，建议使用vs code来编写文档，它非常方便预览文档，可参考《使用vscode编写rst文件》来搭建vscode预览sphinx文档的环境。

编写文档时的语法和规范可参考以下内容：

1.3. 编译文档¶

如果使用了vscode的rst插件，可以直接保存rst文件后它会自动编译并可预览。

也可以手动编译，到文档源码所在的makefile目录，执行如下命令：

#在文档的makefile目录下执行

#Windows指令
make.bat  html
#Ubuntu指令
make html

在设定的build或_build的html目录下会生成静态的html文件。可直接使用这些静态的html文件制作网站。

1.4. 在本地预览文档¶

vscode插件预览有时不够完整，可以在本地开启一个python服务器来预览。进入到生成的_build/html目录，运行如下指令：

#在生成的html目录执行如下指令
#Windows
py -3 -m http.server  8000

#Ubuntu
python3 -m http.server 8000

运行指令后，在浏览器中打开 http://localhost:8000 即可查看生成的静态网页。

1.5. 允许其它主机预览文档¶

类似地，若要允许其它主机访问自己的文档，执行如下命令即可

#在生成的html目录执行如下指令
#Windows
py -3 -m http.server --bind 0.0.0.0 8000

#Ubuntu
python3 -m http.server --bind 0.0.0.0 8000

运行指令后，在浏览器中打开 http://主机IP:8000 即可查看生成的静态网页。

1.6. 清除编译输出¶

有时html文件不会完全达到我们修改rst后的效果，这可能是因为之前的旧文件影响，这时可以先清除编译输出再重新编译。

#清除编译输出

#Windows指令
make.bat  clean
#Ubuntu指令
make clean

#重新编译

#Windows指令
make.bat  html
#Ubuntu指令
make html

1.7. 创建全新的sphinx文档¶

若不想使用本工程模版，可以使用如下指令创建全新的文档。

sphinx-quickstart

按照提示回答问题即可。推荐使用默认的_build目录，与vscode保持一致。其中提示语言时可以使用这个中文代码：zh_CN

sphinx默认不支持markdown语法，要支持的话请参考本模版的conf.py文件配置。