ReadtheDocs - 项目文档管理

针对项目文档,之前项目中依赖gitbook实现官网的展现,后又在hexo的影响下,做了优化版的官网。最近学习Python,发现文档很多都保持有一致性,查来是使用了Read the Docs.
从了解到的构建过程,发现整体思路和hexo基本一致,发布流程如下:

  1. git创建仓库
  2. 本地使用Sphinx进行编译,更换主题sphinx_rtd_theme,利用recommonmark插件支持md
  3. 提交git仓库
  4. readthedocs官网注册,关联仓库进行发布
    想必hexo博客管理,功能比较复杂,readthedocs更适合写官网文档,这种简洁单一大概也印证了python的禅意。
    使用步骤:

  5. install sphinx

pip install sphinx sphinx-autobuild sphinx_rtd_theme

mkdir testbook
cd testbook
sphinx-quickstart # 使用separate目录

生成结构

.
├── build
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.rst
    ├── _static
    └── _templates
  1. install recommonmark 通过recommonmark 来支持markdown
pip install recommonmark

添加一篇文章,在source目录下新建hello.md,内容如下:

# hello,world
=============

index.rst 增加hello:

.. toctree::
   :maxdepth: 2

   hello

更改主题 sphinx_rtd_theme:
更改source/conf.py:

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

支持md,更改conf.py:

from recommonmark.parser import CommonMarkParser
source_parsers = {
    '.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']

补充:支持多级目录

.. toctree::

   python/python
   swift/swift
  1. 编译输出: make html 参考链接
@2017-05-07 14:01