在线文档部署方案:Sphinx + Read the Docs

 

前言Sphinx是一个基于Python的用于创建文档的工具。它最早是用来制作Python语言的帮助文档。具有以下特征: 输出格式:HTML(包括Windows HTML Help),LaTeX(用于打印的PDF版本),ePub,Texinfo, 手册页,纯文本; 强大的交叉引用:语义标记和对函数、类、引用、术语表和类似信息的自动链接功能; 层次结构:简单的文本树定义,并能自动链接同级、...

前言

Sphinx是一个基于Python的用于创建文档的工具。它最早是用来制作Python语言的帮助文档。具有以下特征:

  • 输出格式:HTML(包括Windows HTML Help),LaTeX(用于打印的PDF版本),ePub,Texinfo, 手册页,纯文本;
  • 强大的交叉引用:语义标记和对函数、类、引用、术语表和类似信息的自动链接功能;
  • 层次结构:简单的文本树定义,并能自动链接同级、父级和子级;
  • 自动索引:一般索引以及语言特定模块索引;
  • 代码处理:利用Pygments实现代码高亮;
  • 开放的扩展:支持代码块的自动测试,并包含Python模块的自述文档(API docs)等。

Sphinx使用reStructuredText作为标记语言,它的优势来自于reStructuredText语言的强大和直接,及其解析和翻译套件Docutils

安装和快速开始

对于已经安装有Python的系统,可以直接使用pip安装Sphinx:

pip install sphinx sphinx-autobuild

完成安装之后,可以在命令窗口输入sphinx-build -h来查看sphinx的版本号和该指令的其他控制参数。

在macOS平台下,使用Homebrew安装是更加便捷的方式之一,安装完成后需要将其添加至PATH中:

brew install sphinx-doc
brew link sphinx-doc --force

关于不同平台下更详细的安装说明,可参考Installing Sphinx

在需要创建文档的目录下,直接在命令行中输入:

sphinx-quickstart

就会进入Sphinx的创建向导,通过回答一系列问题就能够创建一个Sphinx工程的空白模板(确保关于autodoc的选项设置为yes)。

在完成了向导配置之后,运行

make html

就可以生成html形式的文档了,虽然它还是空白的。

还可以使用sphinx-autobuild来自动重载文档。运行下面指令来实现:

sphinx-autobuild . _build/html

添加内容

如果要想快速开始使用Sphinx,可以参考First Steps with SphinxSphinx初尝

更加详细的说明文档可参考Sphinx documentationSphinx 使用手册

配置文档

使用sphinx-quickstart指令将生成包括conf.py在内的配置文件,以及一份主文档文件index.rst

conf.py文件包含了该sphinx工程的所有配置选项,包括一些无法在sphinx-quickstart向导中进行设置的复杂选项。更加详细的conf.py配置内容可参考The build configuration file

rST简介

reStructuredText是一种易于阅读、所见即所得的纯文本标记语言。它非常利于快速创建简单的网页和独立的文档,尤其是程序的参考手册。reStructuredText是专门为了特定应用的扩展性而设计的,它的解析器是Docutils的一个组件。

这篇文章告诉了你为何不要使用Markdown进行文档写作:Why You Shouldn’t Use “Markdown” for Documentation,主要原因有以下几点:

  • Lack of a standard
  • Flavors
  • Lack of Extensibility
  • Lack of Semantic Meaning
  • Lock In and Lack of Portability

reStructuredText为用户提供了快速入门指南和参考手册:

更加详细的说明文档可参考reStructuredText PrimerreStructuredText 简介

或者也可以参考这里:reStructuredText 简明教程reStructuredText简明教程

文档托管

Read the Docs是一个基于Sphinx的在线文档托管系统,使得文档完全可搜索且易于查找。它从在线的Subversion、Bazaar、Git或Mercurial仓库获取到基于Sphinx创建的文档代码,生成文档并为用户托管。

Read the Docs是一个开源的项目,可以免费地在GitHub上获取到项目源代码

在完成文档的创作之后,只需将文档工程托管在GitHub上,并在Read the Docs网站上创建账号导入GitHub中对应的工程,网站就能够自动帮助你进行编译和发布。

前往Getting Started Guide来了解如何在readthedocs上进行文档托管。

同时,readthedocs在GitHub上也有为初学者准备的演示代码,供大家学习使用。

延伸阅读