Sphinx文档评论系统

我在折腾 原生Android适配使用国行三星Galaxy Watch 4 ，意外发现 非国行的Android不能使用国行的Watch4？不指望三星，自力更生完美解决 博主 雪糕博客 使用了 utterances 作为 Hugo文档 的评论系统，非常巧妙和灵活:

  • 依靠稳定的 GitHub issues 作为数据存储，背靠大树好乘凉: GitHub可靠性和稳定性肯定比自建博客评论系统要稳定多了

  • 虽然GitHub已经被墙，但是作为纯技术博客来说，受众基本上都是能够翻墙自己折腾的同行

  • 如果用户看不到评论(例如墙内没有架梯子)，那么通过简单的提示也可以让用户知道为何看不到

安装 Utterances

  • 在GitHub上需要安装 utterances GitHub App ，也就是 A lightweight comments widget built on GitHub issues ，访问 utterances GitHub App 页面，点击 Installation 按钮； 或者在 GitHub Marketplace / Apps / utterances 中也可以找到安装入口

    • 选择GitHub账号，然后 下一步

    • 选择需要安装 utterances 的仓库，例如，这里是我的仓库 huataihuang/cloud-atlas :

../../../_images/install_utterances.png

安装 utterances 时选择指定仓库

  • 安装完成后，在自己的 GitHub Settings >> Installations 会看到刚才安装的应用 utterances 应用，并且提供了 Configure 配置按钮来调整刚才的完成的配置

备注

一切就绪(已经完成GitHub端配置)，现在就是如何在Sphinx文档中嵌入和引用 Utterances 来实现直接在GitHub中提交issues(讨论)

评论模版(template)

我是在阅读 基于 utterance 插件为博客部署评论系统（适用于 Sphinx 文档） 受到启发的，原文采用直接修改 sphinx_rtd_theme layout.html 来引用自定义的 comments.html 。我想到之前自己采用 Sphinx文档自定义页脚 扩展默认 layout 不就是能够采用这种方法么。

备注

本段在 Sphinx文档自定义页脚 基础上完成(已经完成默认 layout 扩展，增加了页面的自定义footer)

修改 conf.py 指定模版目录
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

{% extends '!footer.html' %}

{% block extrafooter %}
    <!-- your html code here -->
    <br>
    <p><a href="https://github.com/huataihuang/cloud-atlas/issues">留言和讨论</a>|<a href="https://github.com/huataihuang/cloud-atlas/blob/master/source/donate.rst">请我喝一杯咖啡 👈</a></p>
    <br>
    <p>网站采用 <a href="https://utteranc.es/">utterances</a> 评论系统，所有评论存储在<a href="https://github.com/huataihuang/cloud-atlas/issues">GitHub issues</a> 中，如果你看不到下方的评论框，那么可能需要<a href="https://cloud-atlas.readthedocs.io/zh-cn/latest/linux/security/vpn/index.html">自备梯子</a> 👈</p>
    <div class="articleComments">
        {% include "comments.html" %}
    </div>
{% endblock %}

  • 然后在 _templete/comments.html 引用 utterances 的 clients.js :

_templete/comments.html 中 repo 配置行设置对应GitHub仓库
<comments>
  <script src="https://utteranc.es/client.js"
    repo="huataihuang/cloud-atlas"
    issue-term="pathname"
    theme="github-light"
    crossorigin="anonymous"
    async>
  </script>
</comments>

  • 现在可以开始 make html 输出文档了

sphinx-comments 插件(归档参考)

Sphinx Comments 开源Comments系统完美结合了 utterances 和 Sphinx文档 ，正是我所需期待的文档评论功能的利器。

备注

实际上我最后没有采用这里介绍的 Sphinx Comments 插件，原因是我之前已经采用了 Sphinx文档自定义页脚 ，和 sphinx-comments 插件貌似冲突。所以我实际采用了上文直接修订 Sphinx文档自定义页脚 嵌入一段 utterances client.js 来实现。原理其实和 sphinx-comments 类似

安装和配置 sphinx-comments

pip (Python包管理器) 安装 sphinx-comments
pip install sphinx-comments

  • 然后修改 conf.py :

在 Sphinx文档 配置中激活 sphinx-comments
...
extensions = [
   "sphinx_comments"
]
...
comments_config = {
   "utterances": {
      "repo": "huataihuang/cloud-atlas",
      "optional": "config",
   }
}

  • 然后开始 make html 编译输出文档

参考