用Sphinx快速制作文档

简介

Sphinx 是一种文档工具,它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发. 新版的Python文档就是由Sphinx生成的, 并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持. 本站当然也是使用 Sphinx 生成的,它采用reStructuredText! Sphinx还在继续开发. 下面列出了其良好特性,这些特性在Python官方文档中均有体现:

  • 丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual pages(man 文档), 纯文本
  • 完备的交叉引用: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息
  • 明晰的分层结构: 可以轻松的定义文档树,并自动化链接同级/父级/下级文章
  • 美观的自动索引: 可自动生成美观的模块索引
  • 精确的语法高亮: 基于 Pygments 自动生成语法高亮
  • 开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API docs)等

Sphinx 使用 reStructuredText 作为标记语言, 可以享有 Docutils 为reStructuredText提供的分析,转换等多种工具.

安装Sphinx

Sphinx为Python语言的一个第三方库。我们需要在终端中输入下列命令进行安装:

pip install sphinx

创建Sphinx项目

创建一个用于存放文档的文件夹,然后在该文件夹路径下运行下列命令快速生成Sphinx项目:

sphinx-quickstart

接下来会让你选择一些配置:

  1. 设置文档的根路径(回车,使用默认设置) 12Enter the root path for documentation.> Root path for the documentation [.]:
  2. 是否分离source和build目录(输入y,选择分离,方便管理) 1234You have two options for placing the build directory for Sphinx output.Either, you use a directory "_build" within the root path, or you separate"source" and "build" directories within the root path.> Separate source and build directories (y/n) [n]:
  3. 设定模板前缀(回车,使用默认选项) 1234Inside the root directory, two more directories will be created; "_templates"for custom HTML templates and "_static" for custom stylesheets and other staticfiles. You can enter another prefix (such as ".") to replace the underscore.> Name prefix for templates and static dir [_]:
  4. 输入项目名称和作者 123The project name will occur in several places in the built documentation.> Project name: Sphinx-test> Author name(s): test
  5. 输入项目版本号 1234567Sphinx has the notion of a "version" and a "release" for thesoftware. Each version can have multiple releases. For example, forPython the version is something like 2.5 or 3.0, while the release issomething like 2.5.1 or 3.0a1. If you don't need this dual structure,just set both to the same value.> Project version []: 1.0.0> Project release [1.0.0]:
  6. 文档语言(回车,默认即可) 1234567If the documents are to be written in a language other than English,you can select a language here by its language code. Sphinx will thentranslate text that it generates into that language.For a list of supported codes, seehttp://sphinx-doc.org/config.html#confval-language.> Project language [en]:
  7. 设定文档文就按的后缀 123The file name suffix for source files. Commonly, this is either ".txt"or ".rst". Only files with this suffix are considered documents.> Source file suffix [.rst]:
  8. 设定首页名称(回车,选择默认index即可) 12345One document is special in that it is considered the top node of the"contents tree", that is, it is the root of the hierarchical structureof the documents. Normally, this is "index", but if your "index"document is a custom template, you can also set this to another filename.> Name of your master document (without suffix) [index]:
  9. 根据需要选择是否开启epub输出(一般用不到,回车默认不开启即可) 12Sphinx can also add configuration for epub output:> Do you want to use the epub builder (y/n) [n]:
  10. 根据需求选择是否开启相应的Sphinx拓展功能 12345678910111213Please indicate if you want to use one of the following Sphinx extensions:> autodoc: automatically insert docstrings from modules (y/n) [n]: y> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y> coverage: checks for documentation coverage (y/n) [n]: y> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: yNote: imgmath and mathjax cannot be enabled at the same time.imgmath has been deselected.> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y> viewcode: include links to the source code of documented Python objects (y/n) [n]: y> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: n
  11. 创建项目 1234567891011121314151617A Makefile and a Windows command file can be generated for you so that youonly have to run e.g. `make html' instead of invoking sphinx-builddirectly.> Create Makefile? (y/n) [y]: y> Create Windows command file? (y/n) [y]: yCreating file ./conf.py.Creating file ./index.rst,.md.Creating file ./Makefile.Creating file ./make.bat.Finished: An initial directory structure has been created.You should now populate your master file ./index.rst,.md and create other documentationsource files. Use the Makefile to build the docs, like so: make builderwhere "builder" is one of the supported builders, e.g. html, latex or linkcheck.

项目创建以后目录结构如下所示:

.
├── Makefile
├── build
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst
  • build:用来存放通过make html生成文档网页文件的目录
  • source:存放用于生成文档的源文件
  • conf.py: Sphinx的配置文件
  • index.rst: 主文档定义文档结构 主文档index.rst的主要功能是被转换成欢迎页, 它包含一个目录表( “table of contents tree”或者 toctree ). Sphinx 主要功能是使用 reStructuredText, 把许多文件组织成一份结构合理的文档.

toctree指令初始值如下:

.. toctree::
   :maxdepth: 2

你可以在 content 的位置添加文档列表:

.. toctree::
   :maxdepth: 2
   tutorial.md
   ...

注:文档文件放在与index.rst同级目录下。

支持markdown文件、更改文档主题

Spinx本身不支持.md文件生成文档,需要我们使用第三方库recommonmark进行转换。 首先分别运行下列命令安装recommonmark与sphinx_rtd_theme库。

pip install recommonmark
pip install sphinx_rtd_theme

安装好,在conf.py中修改下列两个配置:

source_suffix = ['.rst', '.md', '.MD']
html_theme = 'sphinx_rtd_theme'

并新增:

source_parsers = {
    '.md': CommonMarkParser,
    '.MD': CommonMarkParser,
}

生成文档

在Sphinx项目所在的文件夹路径下运行下列命令生成文档:

make html

生成后的文档位于build/html文件夹内,用浏览器打开index.html即可看到生成后的文档。


参考文章

  1. Sphinx 使用手册
  2. 使用 sphinx 制作简洁而又美观的文档
  3. 使用Sphinx制作说明文档

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏雪胖纸的玩蛇日常

python3+django2 开发易语言网络验证(上)

44140
来自专栏openshift持续集成

jenkins邮件插件中的内容参数设置

众所周知,Jenkins默认提供了一个邮件通知,能在构建失败、构建不稳定等状态后发送邮件。但是它本身有很多局限性,比如它的邮件通知无法提供详细的邮件内容、无法定...

1.1K80
来自专栏源码之家

无法在发生错误时创建会话,请检查 PHP 或网站服务器日志,并正确配置 PHP 安装

27680
来自专栏difcareer的技术笔记

最新版MacOS(10.13.2)编译Android 4.4.4源码

网上搜一下Mac编译Android源码,能搜到很多,但最新版的MacOS(10.13.2)编译Android4.4.4的却没有,本文记录我的编译过程。

18640
来自专栏Jerry的SAP技术分享

SAP CRM和C4C的内容管理(Content Management)

SAP CRM使用Attachments这个UI给用户提供内容管理的功能。通过新建按钮可以上传本地文档到CRM系统:

61430
来自专栏醉梦轩

Ubuntu安装Proxychains

1.8K30
来自专栏游戏杂谈

Cocos2d-x V2.x版本对64bit的支持

我所使用的是cocos2d-x V2.0版本,而且源码有部分代码是修改过的。好在cocos2d-x官方已经放出了一个支持64位的2.2.6版本,可以做为参考。

28220
来自专栏北京马哥教育

10 个最不流行的 Linux 命令

英文:Tecmint,编译:Linux中国/Luoxcat linux.cn/article-2265-1.html 在本文中,我们将关注几个不为人知的Lin...

37470
来自专栏calvin

jira webhook 事件触发并程序代码调用jenkins接口触发构建操作

开发管理工具触发站点构建事件,事件处理中需要调用Jenkins接口开始构建动作。 我的应用场景: 使用jira作为管理工具,在jira中创建自定义的工作流来...

1K30
来自专栏阿杜的世界

RocketMQ学习-消息发布和订阅

前面一篇文章分析了broker的启动过程,浏览了broker的基本功能。接下来的几篇文章,准备按照十分钟入门RocketMQ一文中提到的一系列特性,依次进行学习...

1.2K20

扫码关注云+社区

领取腾讯云代金券