read-the-docs托管学习笔记

内容简介：read-the-docs托管学习笔记

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 后效果如下:

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上 push 用 sphinx-quickstart 生成的项目, build 目录可以设置到.gitignore中
2. 登录 readthedocs ,注册账号, Connected Services 中授权 github
3. dashboard 中 Import 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

以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持 码农网

关注我们，获取更多IT资讯^_^

查看所有标签

• 【每日笔记】【Go学习笔记】2019-01-04 Codis笔记
• 【每日笔记】【Go学习笔记】2019-01-02 Codis笔记
• 【每日笔记】【Go学习笔记】2019-01-07 Codis笔记
• Golang学习笔记-调度器学习
• Vue学习笔记（二）------axios学习
• 算法/NLP/深度学习/机器学习面试笔记

本站部分资源来源于网络，本站转载出于传递更多信息之目的，版权归原作者或者来源机构所有，如转载稿涉及版权问题，请联系我们。