-
环境准备
Linux CentOS 7
-
方案
搭建一个文档网站，本文档使用的是tomcat+sphinx。
Tomcat可以快速搭建出http服务，也可以使用apache httpd。
Sphinx作为文档网页自动生成工具，可以从reStructured文档转换为html文件。
-
Tomcat安装
- 创建/usr/local/tomcat目录，
- 到tomcat官网下载压缩包，拷进/usr/local/tomcat解压。
- 修改配置文件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）
- Sphinx安装：pip install -U Sphinx
中间遇到无法卸载pyparsing 1.6.5问题，使用：pip install -I pyparsing==2.2.0
- 安装主题sphinx-rtd-theme：pip install sphinx-rtd-theme
- 运行：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:introsections/*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 htmlLinux个人开发机上非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
