[How TO]-如何使用Sphinx编写漂亮的文档

快速链接:
.
👉👉👉 个人博客笔记导读目录(全部) 👈👈👈

关键词:Sphinx, readthedocs, reStructuredText

背景

在当下一些主流的开源社区、公司公开或非公开的项目，都采用了Sphinx+readthedocs方案。这种编写文档的方式，每一个开发者都可以参与，都可以提交自己的文档…
写文档就像写代码一样，可以多人协助

环境搭建-安装Sphinx工具

环境要求: ubuntu, 已安装过python3,make,git等工具, 如果没有安装过，可以使用下列命令进行安装：

sudo apt install git
sudo apt install make
sudo apt install python3
sudo apt install python3-pip

接下来就是安装Sphinx及其依赖了：

pip3 install -U Sphinx
pip3 install sphinx-autobuild
pip3 install sphinx_rtd_theme
pip3 install recommonmark
pip3 install sphinx_markdown_tables

安装换成此后

test@test-21:~/workspace$ sphinx-
sphinx-apidoc      sphinx-autobuild   sphinx-autogen     sphinx-build       sphinx-quickstart 

创建一个项目

使用sphinx-quickstart命令可快速创建一个项目

项目创建后，自动生成如下文件：

编译项目

敲击make html即可完成编译

编译后，用浏览器打开build/html/index.html，即可看到漂亮的界面了：

补充知识：

• make html // 编译，输出html
• make singlehtml //编译，生成单个html
• make latexpdf //编译，生成pdf文件