如何搭建Sphinx文档

• 环境准备

Linux CentOS 7

• 方案

搭建一个文档网站，本文档使用的是tomcat+sphinx。

Tomcat可以快速搭建出http服务，也可以使用apache httpd。

Sphinx作为文档网页自动生成工具，可以从reStructured文档转换为html文件。

• Tomcat安装

1. 创建/usr/local/tomcat目录，
2. 到tomcat官网下载压缩包，拷进/usr/local/tomcat解压。
3. 修改配置文件conf/server.xml，将端口号8080改为80。

    <Connector port="80" protocol="HTTP/1.1"

               connectionTimeout="20000"

               redirectPort="8443" />

<!-- A "Connector" using the shared thread pool-->

       4.启动tomcat，运行bin/startup.sh

静态网页放到tomcat的webapps目录下即可通过访问。

• Linux Sphinx安装（用于转换reStructured文档为html）

1. Sphinx安装：pip install -U Sphinx

中间遇到无法卸载pyparsing 1.6.5问题，使用：pip install -I pyparsing==2.2.0

1. 安装主题sphinx-rtd-theme：pip install sphinx-rtd-theme
2. 运行：sphinx-quickstart产生项目框架。

需要在conf.py中import主题，参考该文档：Sphinx 基础教程_如若明镜的博客-CSDN博客_sphinx 教程

• 生成项目代码

运行：sphinx-quickstart

该步骤只需要执行一次即可。

build：生成的文件的输出目录
source: 存放文档源文件
_static：静态文件目录，比如图片等
_templates：模板目录
conf.py：进行 Sphinx 的配置，如主题配置等
index.rst：文档项目起始文件，用于配置文档的显示结构
make.bat：Windows 命令行中编译用的脚本
Makefile：编译脚本，make 命令编译时使用

•  编辑文档框架及文档内容

文档内容都存放在source目录下。

主文档index.rst主要用于生成框架目录，结构如下：

Welcome to testdoc's documentation!
===================================

.. toctree::
   :maxdepth: 2
   :glob:

   intro
   sections/*

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

其中，intro为子文档intro.rst, sections/*会包含同级section目录下所有rst文档。

Sphinx文档结构参考：

The TOC tree — Sphinx 1.3.1 documentation

 

Sphinx使用的是结构化文本，主要语法参考：

reStructuredText 入门 — Sphinx 1.3.1 documentation

Create Documentation with RST, Sphinx, Sublime, and GitHub — RST | Sphinx | Sublime | GitHub documentation

•  生成文档网页

清理命令：

make clean

生成网页命令：

make html

Linux个人开发机上非root用户需要加sudo执行以上命令:

sudo make html

生成的主网页：build/html/index.html

• 文档网站

将项目生成的html下所有文件拷贝至/usr/local/tomcat/apache-tomcat-9.0.54/webapps目录下的个人相关目录，如/usr/local/tomcat/apache-tomcat-9.0.54/webapps/demo

cd build/html
sudo cp -fr * /usr/local/tomcat/apache-tomcat-9.0.54/webapps/demo

使用http://ip/demo/index.html 访问。

• 拓展功能

支持markdown

只需要按照python包：pip install recommonmark sphinx-markdown-tables

并修改对应的conf.py

extensions = [
    'recommonmark',
    'sphinx_markdown_tables'
    ]

这样Sphinx就可以识别带md后缀的markdown文件，如README.md