前阵子在看到一个公众号的哥们使用 readthedoc 模板搭建了一个个人的文档站点,因为之前也看到过,一直想弄却被拖延了,刚好最近项目组有需求就顺手搭了一个。

1. 安装 Sphinx

Sphinx是一个基于 Python 的文档生成项目,最早只是用来生成 Python 官方文档,随着工具的完善,越来越多的知名的项目也用他来生成文档。

Sphinx默认使用reStructuredText作为文档写作语言, 当然也可以通过模块支持其他格式,比如我喜欢的MarkDown格式。

Sphinx的原理很简答,就是把特定格式书写的文档,通过约定的转换方式,生成对应的 HTML 文档。这里书写的文档可以支持多种格式,生成的 HTML 也可以支持多种模板。

Sphinx安装非常简单,通过如下命令即可:

pip install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark

2. 创建一个文档项目

安装好Sphinx之后,我们就可以通过它来创建实际的文档项目,主要命令如下:

mkdir -p /data/testdocs
cd /data/testdocs
sphinx-quickstart
# 进入文档创建选项过程

进入文档创建选项过程之后,按照自己的需求来选择具体选项。个人建议的选项分别如下:

> Separate source and build directories (y/n) [n]: y
> Project name: testdocs
> Author name(s): chenxiaowu
> Project release []: 0.1
> Project language [en]: zh_CN

完成这些选项之后,在/data/testdocs目录下就会创建一个文档项目。其目录结构如下:

├── build
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.rst
    ├── _static
    └── _templates

3. 编写第一个文档

现在开始就可以创建真正的文档了,具体需要 3 步:

  1. 在 source 目录下创建一个.rst 的文件,如:hello.rst
  2. 文件内容为 rst 格式文本
  3. 修改 source/index.rst 文件,添加新增的 hello.rst 文件

hello.rst文件内容如下:

hello, python
==============

index.rst文件修改如下:


Contents:
.. toctree::
   :maxdepth: 2

   hello

完成这些步骤之后,直接返回/data/testdocs目录,使用如下命令生成 html 文件。

make html

想要访问生成后的 html 内容,可以通过/data/testdocs/build/html/index.html路径来查看。默认的效果如下:

当然,如果你希望其他人也能访问到这个网页,最好的办法就是搭建一个nginx服务,来代理这些静态的 html 文件即可!

4. 修改 html 模板

现在你已经可以开始编写发布你的文章和文档了,只是使用的是默认的写作语言和默认的 html 模板,如果你希望使用额外的支持,可以选择性的执行下面 2 个步骤。

除了默认 html 模板外,你当然可以自定义模板了;除此之外还有一个比较流行的模板 -- readthedoc 官网使用的模板。其配置方式只要修改一下source/conf.py文件即可。

# 文件头部添加如下内容
import sphinx_rtd_theme
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

# 修改原来的html_theme值为
html_theme = "sphinx_rtd_theme"

之后,再次执行make html命令重新编译一下;再次访问index.html网页,其效果如下:

对我而言,2 个模板都是可以接受的;第一个模板也有很多开源工具在用,比如:flask 官网;第二个更是 readthedoc 的主题模板。

5. 支持 markdown

如果你跟我一样,之前一直是使用markdown的,又不想仅仅为了写文档而学习一门新的写作语言,那么你也可以让它支持markdown语法。

想要配置markdown支持,同样只要修改source/conf.py文件就可以了。主要有 2 处修改:

# 首先在头部添加一条语句
import recommonmark

# 修改原来的extensions为
extensions = [
    'recommonmark'
]

保存修改的配置,并在source目录下创建一个markdown.md文件,其内容如下:

# Test Markdown

## header 1

### header 2

重新执行make html之后,再次访问网页的效果如下:

当然,官方支持的reStructuredText语言,能够支持的格式会更多。比如:markdown中的表格就不被支持。所以如果你想尝试的话,可以看看这里的教程https://zh-sphinx-doc.readthedocs.io/en/latest/contents.html

关注二维码


↙↙↙阅读原文可查看相关链接,并与作者交流