内容简介: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/深度学习/机器学习面试笔记
本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们。