Sphinx快速入门
 doctorrm      2019-01-23 21:39:50      28      0      

Sphinx是啥

简单看就是一个Python写的文档软件,用来做文档的,类似于GitBook,但比GitBook有更多的功能和效果,只是文档语言是自定义的(rst),不像GitBook那样可以用MarkDown。例子如下:

安装

pip install sphinx

注:貌似 easy_install -U Sphinx 也可以。

重要:在安装完sphinx之后,下面的步骤都是自定义的了,如果你有现成的文档,其实就可以直接复制到暴露的文件夹下面,即可访问。

定义文件结构

执行上述命令之后,sphinx会在源文件目录中自动生成conf.py文件以及index.rst。index.rst称之为主文档,它被sphinx作为欢迎页面。

index.rst中包含了目录树指令toctree,sphinx使用它链接其他子文档。

toctree指令的初始值为空:

.. toctree::
   :maxdepth: 2

接下来就可以给它添加子文档的链接了,直接使用文档的名称即可,省略掉文件后缀,如果是多级目录,则使用/分隔开。

.. toctree::
   :maxdepth: 2

   intro
   tutorial
   chapter/doc1
   ...

接着我们就可以创建上面列出的文件并添加相应内容了,sphnix会自动将这些文档的章节标题插入到doctree指令的位置。

添加内容

在sphinx源文件中,使用reStructuredText标记语言进行文档编写,除此之外,sphinx还格外提供了一些指令。

具体可以参考reStructuredText Primer以及Sphinx Markup Constructs

设置源文件目录

包含.rst文件的根目录称之为源文件目录,目录中还包含sphinx的配置文件conf.py。

进入源文件目录,执行以下命令,会指引用户配置整个项目:

sphinx-quickstart

生成文档

使用下面的命令生成文档:

$ sphinx-build -b html source build

source指源文件目录,生成的文档放置在build指定的目录中。(build可以改成一个目标路径

实际上还有一个更简便的方法,sphinx-quickstart生成了一个make.bat文件,可以直接运行这个脚本:

make html(未测试)

上述命令会直接在源文件目录中生成文档。

设置主题

推荐使用readthedoc使用的主题,美观又简洁大方。
首先安装主题库:

pip install sphinx_rtd_theme

然后配置conf.py(位于source目录下):

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
去打赏

您的支持将鼓励我们继续创作!

[微信] 扫描二维码打赏

[支付宝] 扫描二维码打赏

正在跳转到PayPal...

发表评论