sphinxcontrib.contributors 1.0

介绍

Sphinx 是一个用 Python 编写的软件开发文档工具。它被成百上千个项目使用，其中一些可以在 readthedocs.org 上找到。

sphinxcontrib.contributors Sphinx 扩展添加了一个侧边栏框，显示文档的贡献者。这些信息来自 Git 提交和 Github 用户资料。

经常编写开源软件文档是一项没有回报的任务。提供文档常常被许多软件开发者忽视。编写文档的人无法像摇滚明星开发者那样成为焦点。通过在 Sphinx 侧边栏添加一个新框，sphinxcontrib.contributors Sphinx 扩展通过给文档页面的作者提供“曝光”和“链接”来鼓励编写文档。

好处

• 给予应得的赞誉

• 该过程基于 git 历史自动进行，无需单独的贡献者列表

• 表明文档是由人编写的，不是自动生成的

• 鼓励人们编写更多文档

示例

参见 Plone 开发者文档。

安装

将软件包安装到您的虚拟环境中

pip安装sphinxcontrib.contributors

安装此扩展所需模板和静态媒体文件。您可以从这里下载文件。使用Github原始文件视图下载文件。

将以下文件添加到您的Sphinx 静态 资源文件夹中

transparency.min.js
contributors.js
contributors.css

将以下文件添加到您的Sphinx 模板 文件夹中

contributors.html

用法

Sphinx HTML已配备获取特定文件提交信息的Github API URL。然后使用JavaScript AJAX请求来获取提交信息。作者从提交中解析。

您会得到每个作者的Github用户名作为工具提示，Github个人资料链接和Github头像。

• 如果可用Github用户名，则显示Github Gravatar或Identicon，并提供链接到Github个人资料页面

• 如果提交者不是Github作者，则提交者的名字显示在空白图片上

限制

目前，作者是在客户端使用Github公共API解析的。这对于低流量文档托管是合适的。

• 在文档构建期间解析作者会增加构建时间

• 对于大型文档构建，您可能会达到Github API限制阈值，使得持续文档构建变得困难

源代码和问题跟踪

在Github上查看项目.

其他

该扩展使用git命令和Python sh库来提取Git仓库信息。《Transparency客户端语义模板库》用于从Github API JSON生成面向链接的DOM树。

这个项目是在Plone 会议2013上，与一群优秀的人、许多卡皮林哈和许多乐趣一起创建的。

作者

Mikko Ohtamaa（《博客》，《Facebook》，《Twitter》，《Google+》）

变更日志

1.0 (2013-10-07)

• 初始发布[miohtama]