内容简介：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发布
- github上
push用sphinx-quickstart生成的项目,build目录可以设置到.gitignore中 - 登录 readthedocs ,注册账号,
Connected Services中授权github - dashboard 中
Import a Porject导入github中的项目然后build
Webhooks监听github提交
- 在文档项目的
setting中选中Webhooks & Services, - 在
Services项中点击Add service - 选择
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
以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持 码农网
猜你喜欢:
- 【每日笔记】【Go学习笔记】2019-01-04 Codis笔记
- 【每日笔记】【Go学习笔记】2019-01-02 Codis笔记
- 【每日笔记】【Go学习笔记】2019-01-07 Codis笔记
- Golang学习笔记-调度器学习
- Vue学习笔记（二）------axios学习
- 算法/NLP/深度学习/机器学习面试笔记
本站部分资源来源于网络，本站转载出于传递更多信息之目的，版权归原作者或者来源机构所有，如转载稿涉及版权问题，请联系我们。
