Sphinx+Versioning+Read the Docs主题实现gitpage自动化部署

个人非常喜欢Read the Docs的文档样式，然而官网上部署的话社区版本会有一个小广告，虽然不影响阅读不过还是很不舒服，而且它并没有提供编译好的静态网页文件（虽然可以右击另存为不过感觉很LOW……）但是因为他是开源的，所以社区还是提供了一些自部署的方法，不过感觉很复杂就没搞了。
但是最近折腾的时候我发现采用Sphinx+Versioning插件+Read the Docs主题可以完美DIY出一套相同风格的文档并可实现gitpage自动化部署，网上都是托管在rtd上的，没有这种的教程，只能自己摸索了。

环境准备

sphinx安装

官方安装文档：http://www.sphinx-doc.org/en/master/usage/installation.html
Debian/Ubuntu：

apt-get install python3-sphinx

Windows：

pip install sphinx

Read the Docs 主题

sphinx 1.4版本后rtd主题不再默认安装，需要自己装：

pip install sphinx_rtd_theme

Versioning插件

Read the Docs主题生成的文件并不包含官方站左下角的版本切换功能（效果：https://docs.readthedocs.io/en/latest/intro/getting-started-with-sphinx.html），因此我们需要用第三方插件实现：https://github.com/Robpol86/sphinxcontrib-versioning
然而很不幸，这个库已经2年多没有维护了，最新版的sphinx编译会报错，可以使用下面这个人fork的项目：https://github.com/leokoppel/sphinxcontrib-versioning
不过我在使用的时候发现last-update等参数还是会有问题，可以用我Fork的修改版：
https://github.com/MXWXZ/sphinxcontrib-versioning
安装方法：

pip install git+https://github.com/MXWXZ/sphinxcontrib-versioning.git

【可选】VSCode-rst扩展配置

搜索插件reStructuredText，几十万下载量的那个就是了，这样就可以预览文件了。如果想要sphinx语法检查需要安装doc8库

pip install doc8

注意目前版本(v0.8.0)存在BUG，如果是在windows下，\r\n换行符会触发D002和D004警告（https://github.com/vscode-restructuredtext/vscode-restructuredtext/issues/84），临时解决方案为在VSCode设置中添加

{
    "restructuredtext.linter.extraArgs": [
        "--ignore D002",
        "--ignore D004"
    ]
}

即可。

Demo实战

基本主题

我们来搭一个Demo版的项目一步一步熟悉设置吧。

1. Github上建立一个test_doc仓库，然后克隆到本地：

2. 终端切换到目录下，执行sphinx-quickstart，回答一系列问题，注意在githubpages选项选y就行

   Welcome to the Sphinx 1.8.2 quickstart utility.
   Please enter values for the following settings (just press Enter to
   accept a default value, if one is given in brackets).
   Selected root path: .
   You have two options for placing the build directory for Sphinx output.
   Either, you use a directory "_build" within the root path, or you separate
   "source" and "build" directories within the root path.
   > Separate source and build directories (y/n) [n]:
   Inside the root directory, two more directories will be created; "_templates"
   for custom HTML templates and "_static" for custom stylesheets and other static
   files. You can enter another prefix (such as ".") to replace the underscore.
   > Name prefix for templates and static dir [_]:
   The project name will occur in several places in the built documentation.
   > Project name: test
   > Author name(s): imwxz
   > Project release []: 1.0
   If the documents are to be written in a language other than English,
   you can select a language here by its language code. Sphinx will then
   translate text that it generates into that language.
   For a list of supported codes, see
   http://sphinx-doc.org/config.html#confval-language.
   > Project language [en]: zh_CN
   The file name suffix for source files. Commonly, this is either ".txt"
   or ".rst".  Only files with this suffix are considered documents.
   > Source file suffix [.rst]:
   One document is special in that it is considered the top node of the
   "contents tree", that is, it is the root of the hierarchical structure
   of the documents. Normally, this is "index", but if your "index"
   document is a custom template, you can also set this to another filename.
   > Name of your master document (without suffix) [index]:
   Indicate which of the following Sphinx extensions should be enabled:
   > autodoc: automatically insert docstrings from modules (y/n) [n]:
   > doctest: automatically test code snippets in doctest blocks (y/n) [n]:
   > intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
   > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
   > coverage: checks for documentation coverage (y/n) [n]:
   > imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
   > mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
   > ifconfig: conditional inclusion of content based on config values (y/n) [n]:
   > viewcode: include links to the source code of documented Python objects (y/n) [n]:
   > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: y
   A Makefile and a Windows command file can be generated for you so that you
   only have to run e.g. `make html' instead of invoking sphinx-build
   directly.
   > Create Makefile? (y/n) [y]:
   > Create Windows command file? (y/n) [y]:
   Creating file .\conf.py.
   Creating file .\index.rst.
   Creating file .\Makefile.
   Creating file .\make.bat.
   Finished: An initial directory structure has been created.
   You should now populate your master file .\index.rst and create other documentation
   source files. Use the Makefile to build the docs, like so:
   make builder
   where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

3. 编辑conf.py，将html_theme的值改成sphinx_rtd_theme，添加：

    html_context = dict(
        conf_py_path='/',
        display_github=True,
        github_repo=project,
        github_user=author,
    )
   
    html_copy_source = False
   
    html_last_updated_fmt = '%c'
   

   （本人常用配置，仅供参考）如果有额外配置可以参考这个

4. 先执行make html看看，打开_build/html目录，浏览器看看index.html，是不是已经换成rtd主题了？

版本切换插件

首先阅读一下官方文档以便正确使用：https://robpol86.github.io/sphinxcontrib-versioning/v2.2.1/index.html
因为必须将修改Push到远程才能生效，所以我们可以新建一个分支gh-pages作为我们Build出来静态文件（也就是gitpage的主页）的发布分支，而master则作为文档源码的分支。

1. master分支需要忽略_build目录，新建.gitignore文件将其添加为例外：

    /_build
   

2. 推送源文件到远程

    git add -A
    git commit -m "xxx"
    git push origin
   

3. Build一下看看效果（详细参数请看官方文档）：

    sphinx-versioning build -abts semver . _build/release
   

   在_build/release目录即可看到有版本切换的文档啦~

4. 新建一个空分支并提交到远程：

    git checkout --orphan gh-pages
    git rm -rf .
    [Linux]touch README.md
    [Windows]type nul>README.md
    git add README.md
    git commit -m "msg"
    git push origin gh-pages
   

5. 推送Build文件到远程：

    sphinx-versioning push -abts semver . gh-pages .
   

现在去Github上看看，是不是自动有了一个EnvironmentTab？进去点View deployment就可以看到成果啦~
以后只需要clone出master分支，修改并push远程后执行第5步即可自动化部署，也可先执行第3步看看效果。