网站文档sphinx-doc

预览

【sphinx_rtd_theme】主题

自带的sphinx主题

简介

【sphinx-doc】是基于python的文档生成器（使用文档推荐【这个】），它使用 reStructuredText 语法(类似markdown)编写文档，通过编译，可以生成html,epub,man,pdf等多种格式，现在也可以通过安装扩展来支持简单的Markdown语法。

安装

• Ubuntu
  python3-sphinx (Python 3) 或者 python-sphinx (Python 2)

  $ apt-get install python3-sphinx

• macOS

  $ brew install sphinx-doc

• Windows

  $ pip install -U sphinx

创建项目

# 新建空项目
$ sphinx-quickstart
# 需要做很多的配置，完成之后目录结构如下：
.
├── _build
├── conf.py
├── index.rst
├── make.bat
├── Makefile
├── _static
└── _templates

3 directories, 4 files
# 编译为html
$ make html

支持Markdown

【教程】
【官网教程】

$ pip install recommonmark

conf.py 加入

extensions = ['recommonmark']

警告：Markdown不支持Sphinx的很多特性，比如内联标记和指令

主题

介绍一个主题【sphinx_rtd_theme】

它是【readthedocs.org】做的一个主题，这个网站本身提供 创建、托管和浏览文档 ，比如它提供的【sphinx文档】比 【sphinx官网】 的好看多了。

【sphinx-rtd-theme的文档】

安装主题

$ pip install sphinx_rtd_theme

conf.py 配置

html_theme = "sphinx_rtd_theme"

【更多主题配置】