使用Sphinx创建你的文档

Sphinx是一个基于Python的文档生成器，它支持使用reStructuredText语法对文档内容进行格式化，同时提供了很多主题风格的文档模板，最常用的就是sphinx-rtd-theme，下面将详细介绍如何使用该主题模板。

依赖环境

• Python

准备环境

安装pip

wget https://bootstrap.pypa.io/get-pip.py
python get-pip.py

安装Sphinx

pip install sphinx sphinxcontrib-httpdomain

安装主题模板

pip install sphinx_rtd_theme

使用

创建文档项目，执行下面命令后按照提示输入相关信息，不清楚的项回车使用默认值即可

mkdir demo
cd demo
sphinx-quickstart

创建完文档项目后会生成相关的配置文件，目录结构如下

_build  #存放最终构建生成的静态html页面
_static  #存放图片、logo等相关资源文件 
_templates  #存放模板文件
conf.py  #项目配置文件
index.rst #文档首页
make.bat #windows下的构建脚本
Makefile #linux下的构建脚本

修改配置文件conf.py

html_theme = "sphinx_rtd_theme"

使用reStructuredText语法编写文档，例如demo.rst，放在index.rst同级目录下

Sphinx
=============

readthedocs
-------------

* hello world!

把demo.rst加入到index.rst中

Welcome to hanshan426's documentation!
===============================

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   
   demo

执行构建命令

make html

构建成功后会在_build\html目录下生成相应的html文件，访问index.html即可

相关资源

• readthedocs
• reStructuredText语法简介
• reStructuredText在线编辑器
• 文档转换神器