read-the-docs托管学习笔记

栏目: 编程工具 · 发布时间: 8年前

内容简介: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 后效果如下:

read-the-docs托管学习笔记

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

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

查看所有标签

猜你喜欢:

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

京东技术解密

京东技术解密

京东研发体系 / 电子工业出版社 / 2014-11-18 / 65

京东高速的增长、闪电响应的供应链、庞大的团队规模等背后内幕,对于业界一直像谜一样神秘。随着成为中国B2C领导厂商以及在纳斯达克上市,京东越来越需要开放自己,与业界形成更好的交流与融合。《京东技术解密》的面世,就是京东技术团队首次向业界集体亮相。本书用翔实的内容为读者逐一解答——如何用技术支撑网站的综合竞争实力,如何把握技术革新的时间点,如何应对各种棘手问题及压力,如何在网站高速运转的情况下进行系统......一起来看看 《京东技术解密》 这本书的介绍吧!

CSS 压缩/解压工具
CSS 压缩/解压工具

在线压缩/解压 CSS 代码

Markdown 在线编辑器
Markdown 在线编辑器

Markdown 在线编辑器

UNIX 时间戳转换
UNIX 时间戳转换

UNIX 时间戳转换