sbosphinx 2.2.0

概述

Safari技术文档现在正在以Sphinx（一个用于从文本文件使用reST（reStructuredText）wiki标记生成HTML、PDF、Epub和其他格式的文档的实用工具）可处理的形式编写和收集。除了直接编写文档外，我们还可以让Sphinx从我们的核心编程语言中抓取API文档

• 使用sphinx-apidoc命令收集Python文档字符串。

• 使用JsDoc Toolkit RST-Template库收集JavaScript中的JSDoc格式注释，该库反过来使用jsdoc-toolkit。

可以使用sphinx-contrib中的httpdomain对Web服务API进行文档化。

安装

pip install sbosphinx

要构建JavaScript API文档，您还需要java和ant。

设置

sbosphinx使用标准的Sphinx conf.py文件，但将大部分配置委托给一个sbo_sphinx.conf模块，这应该适合大多数SBO项目。因此，一个最小的docs/conf.py文件可以非常简单，如下所示

from sbo_sphinx.conf import *

project = 'my_project_name'

还应该有一个docs/index.rst文件作为文档主页；请参见本项目中的示例。

扩展程序自动生成Python和JavaScript API文档的附加设置。有关详细信息，请参阅sbo_sphinx.apidoc和sbo_sphinx.jsdoc。

用法

使用标准的sphinx-build语法。对于希望以HTML格式生成文档的通常情况

sphinx-build -b html . _build

外部文件

位于docs目录层次结构之外的reStructuredText文件不能直接包含在目录表中。要将存储库根目录中的README.rst文件包含在生成的文档中，请在docs目录内创建一个占位符，该占位符使用include指令来获取其内容

.. include:: ../README.rst

例如，请参阅本项目中的docs/readme.rst。

PyPI描述验证

如果PyPI在reStructuredText包描述中遇到不知道如何处理的内容，它会将其静默显示为纯文本，而不是按照预期进行格式化。为了在上传包之前得到一些警告，请安装readme包并运行

python setup.py check --restructuredtext --strict

请注意，为了使其正常工作，必须在setup.py中设置long_description（通常通过从README.rst文件等加载它）。如果您依靠在setup.cfg中设置description-file，则用于PyPI页面的reStructuredText不可用于check命令。

Markdown

Sphinx目前没有真正支持Markdown风格的wiki标记。如果项目有一个README.md文件，您希望将其包含在文档中，有以下几种选择

• 将其转换为README.rst，相应地更改标记。 pandoc可能可以很好地自动化此转换。

• 将文件的reStructuredText格式副本添加到docs目录，并用它代替。然而，这样做存在副本与原始文件不同步的风险。

• 实现一个Sphinx扩展，该扩展使用pandoc自动转换并复制配置列表中指定的Markdown文件。这种方法的一个缺点是它需要在生成文档的每个系统上安装pandoc。

Read the Docs

sbo-sphinx被编写为与Read the Docs服务大部分兼容，但请注意，私有源代码存储库不能在公共Read the Docs服务上使用（但可以在配置适当的私有安装上使用）。

注意

• Python模块的目录页在docs/python/index生成。JavaScript的等效文件（如果已生成）位于docs/javascript/index，还有一个处理过的JS文件列表在docs/javascript/files。这些应添加到文档中的toctree指令。再次查看本项目的docs/index.rst以获取示例。

• 创建从JSDoc注释创建reST文件的RST-Template库目前使用jsdoc-toolkit，该库已不再积极开发。如果我们决定其继任者JSDoc 3有足够的有用改进，我们可以考虑将库更新为使用它。

故障排除

• 错误：未识别的参数 - 如果在解析文档中的代码时出现此错误并中断构建，则很可能是该文件在模块级别使用了argparse或optparse，并且它尝试解析给sphinx-build的命令行参数失败。将此类代码放入仅在if __name__ == '__main__'条件下调用的函数中（即，如果该脚本是被调用的脚本）。

参考

• Sphinx

• reStructuredText语法概述

• JSDoc

• JSDoc 3

• JsDoc Toolkit RST-Template

• sphinx-contrib - 这里有许多有趣的东西；支持 CoffeeScript、Doxygen、Erlang、Excel、Google 图表和地图、RESTful HTTP API、Ruby 等。

• sphinxcontrib.httpdomain - 记录 RESTful HTTP API