关于文档📌

本文档描述了一个伟大组织的传奇（不接受反驳~😊(●'◡'●)）

本文档基于伟大的Sphinx项目构建（你没想错，伟大的Python的文档就是用它整的），我们还使用了同样伟大的GitHub和ReadtheDocs进行文档自动构建和托管，文档写作所使用的文本标记（Markup）语言为reStructuredText + Markdown。文档使用了不怎么帅的主题sphinx-rtd-theme。

如果各位路过的大佬发现文档有写的不对或者可以改进的地方，欢迎向我们提issue和pull request，谢谢啦(●'◡'●)

如何参与文档的编辑与维护✍

由于本文档基于Sphinx，而这玩意是个Python项目，所以你需要安装Python的相关环境，你不需要会Python就可编辑和构建文档。文档的主要依赖（Python Packages）如下：

sphinx

sphinx-rtd-theme

recommonmark

注意❗❗❗：

参与维护前请先 fork 本仓库，然后基于 fork 后的仓库的 master 分支创建一个新的分支（名字随意），修改后提交到这个新的分支，然后基于这个分支向本仓库发送 pull request，会有人对你的 pull request 进行 review，review 通过后会合并到本仓库

如果后续想要继续参与维护，参考以下commit log的同步流程：

添加本仓库为你 fork 后仓库的远程上游 upstream

git remote add upstream https://github.com/seven-innovation-base/SphinxDOC.git
# 或者
git remote add upstream git@github.com:seven-innovation-base/SphinxDOC.git

同步远程上游 upstream 的变更

git fetch upstream

将远程上游的变更合并到你 fork 后的仓库的 master 分支中，保证你的 master 分支永远都是最新的

git merge upstream/master

然后再基于 master 分支新建新的分支，提交你的变更到你所创建的新的分支，最后提交 pull request

一、环境配置

在开始前请先fork一下这个项目，再clone到本地（clone的是你名下的同名仓库）

我们建议你使用virtualenv+pip的方式管理本文档构建所依赖的环境，如果你想使用pipenv或者单纯用pip也行，方法如下：

git clone https://github.com/your_username/SphinxDOC

pip + virtualenv

# 1、转到项目目录
cd SphinxDOC
# 2、安装virtualenv
pip install virtualenv
# 3、为本项目创建虚拟环境
virtualenv venv
# 4、激活虚拟环境
cd venv/Scripts
activate
cd ../..
# 5、安装依赖
pip install -r requiremen.txt
# 6、清除之前构建好的文件
make clean
# 7、试下构建文档
make html
# 8、构建好的静态文件再_build目录下，点击index.html进行预览

pipenv

pip install pipenv

pipenv install  # 创建虚拟环境，安装依赖

pipenv shell  # 激活虚拟环境

./make clean

./make html  # 构建文档，在_build/html/index.html 预览

二、文档编辑与构建

环境搭建好后，就可以编辑*.rst、*.md文件进行文档编辑了，如果你想新增rst、md文件或优化文档结构，请先阅读Sphinx中文文档的文档结构的定义章节

md的格式有限，可以考虑用rst，可以一开始可以用Markdown写然后用pandoc将Markdown格式转换为restructText继续编辑。

如果你已经编辑完成，请先使用make clean清除之前构建好的静态文件，然后使用make html构建新文档，然后进行效果预览(构建好文件位于**_build/html**目录中)，如果没啥毛病就push到GitHub并向我们提交pull request

拓展阅读

感谢以下小伙伴的付出 ✨

_GrayHat
💻

_Mr.Ye
💻

_yizhuang
📖

_Lvshaomei
📖

seven-innovation-base/SphinxDOC