Sphinx + GitHub + ReadtheDocs下快速搭建你的写书平台(1)
年前的公司技术分享会上，小凡姐推荐使用ReadtheDocs、Sphinx来自动生成文档。我之前有了解过，但是一直都没去尝试一下，当时大概整理了一下，还没有发。
我想整理一下是因为我发现网上的资源其实挺少的，我主要参考简书上的一篇文章完成写书项目的搭建。
先大概介绍一下Sphinx，Github，ReadtheDocs
Sphinx我在操作的时候，发现Sphinx本身，既是一个基于python的文档生成工具，同时，sphinx也是一个全文检索工具。所以下载的时候得注意一下。 github是一个代码托管的平台。而ReadtheDocs是一个基于Sphinx的在线文档托管系统。接受一个git Repository 或SVN仓库作为文档来源。
简单说一下，
Github和ReadtheDocs是需要你登录官网，各注册一个账号然后把他们关联起来的，而sphinx是你安装在本地，然后上传Github自动连接ReadtheDocs生成文档的。
任意平台的安装
ubuntu下的安装：
apt-get install python-sphinx
搭建：
创建一个目录，比如study-python.然后进入目录当中。然后执行
sphinx-quickstart
接下来有一系列的操作，大部分回车即可，小部分比如项目名称，用户名称之类的自己根据英文填一下。
创建完成之后目录下有4个文件：
build #运行make命令后，生成的文件都在这个目录里面
source #放置文档的源文件
make.bat #批处理命令
makefile
基本完成，使用make html 命令就可以生成html形式的文档了
配置conf.py
gedit conf.py # 强烈建议用vim打开文件，如果不会vim命令，就用gedit.
找到html_theme="alabaster",然后把引号里面的alabaster替换为sphinx_rtd_theme
然后在你创建的目录下面，也就是你项目的根目录下，执行
git init #注释，初始化仓库
git add . # 添加所有的修改
git commit -m "sphinx start" # 提交到本地
git remote add origin http://github.com/[yourusername]/[yourrepository].git #设置远端 这里面，需要你在github上面提前建好一个repository，然后才能顺利推送成功。
git push origin master #推送到远端git导入到ReadtheDocs
还是在github里面进入到你创建的远端仓库里面，进入settings -> Service 然后添加 readtheDocs，然后你需要进入ReadtheDocs里面创建一个账号(如果没有账号的话），连接你的github账号，把你的仓库导入，导入成功之后，点击阅读文档。就可以看到web效果了。