read-the-docs托管学习笔记

Sphinx

Sphinx是一个基于Python的文档生成项目,采用了reStructuredText作为文档写作语言 ,不过也可以通过模块支持其他格式.
(Sphinx标记结构)[http://www.pythondoc.com/sphinx/markup/]

Sphinx安装

pip install sphinx sphinx-autobuild

快速开始

#创建目录
cd /path/to/project
mkdir docs
#sphinx工作目录基本配置
cd docs
#可以回车按默认配置来写
sphinx-quickstart
#quickstart 后生成的目录结构
readthedocs
│ make.bat
│ Makefile
├─build
└─source
  │ conf.py
  │ index.rst
  ├─_static
  └─_templates
# 默认会有一个index.rst,make html用来生成html页面
make html

添加一篇文章

source目录下新建hello.rst:

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

index.rst修改如下:

Contents:

.. toctree::
:maxdepth: 2

hello

make html后效果如下:
sphinx

toctree 支持多级目录,有时候要区分同文件比如python.rst,swift.rst笔记在不同的目录,toctree这样设置:

Contents:

.. toctree::

python/python
swift/swift

支持markdown编写

pip install recommonmark

更改conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']

更改主题 sphinx_rtd_theme

pip install sphinx_rtd_theme

更改conf.py:

import sphinx_rtd_theme

html_theme = "sphinx_rtd_theme"

html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Github托管, read_the_docs发布

doc

  1. github上pushsphinx-quickstart生成的项目,build目录可以设置到.gitignore中
  2. 登录readthedocs,注册账号,Connected Services中授权github
  3. dashboardImport a Porject导入github中的项目然后build

Webhooks监听github提交

  1. 在文档项目的setting中选中Webhooks & Services,
  2. Services项中点击Add service
  3. 选择ReadTheDocs,点击Active

make nonlocal image URI found waring gone

更改conf.py

import sphinx.environment
from docutils.utils import get_source_line


def _warn_node(self, msg, node, **kwargs):
if not msg.startswith('nonlocal image URI found:'):
self._warnfunc(msg, '%s:%s' % get_source_line(node), **kwargs)

sphinx.environment.BuildEnvironment.warn_node = _warn_node