Sphinx Docs 可以支持 Algolia 的文档搜索吗？

Question

有谁知道 Algolia 的 DocSearch 免费文档服务是否可以集成到 Sphinx 文档网站中？

Answer 1

它绝对可以集成到 Sphinx 文档中，而且非常容易。

我申请了一个帐户并获得了 API 密钥。

阅读：https://community.algolia.com/docsearch/run-your-own.html

我在 Python 2.7 和 MacOS 10.13 下从 github 安装了免费的

docsearch-scraper

，并使用 pipelinenv 和缺失的 dotenv 模块的额外安装后让它工作。

经过一番摆弄后，我根据

config.json

命令的输出使用了自定义的

./docsearch bootstrap

，替换以“lvln”开头的行中所有出现的“FIXME”为“.section”，并替换行中的“FIXME”以“text”和“.document”开头（参见下面的示例）。

我们成功索引了 Sphinx 文档并运行

.docsearch playground

命令打开了一个测试 Web 服务器，该服务器立即提供了出色的结果。

我们使用 readthedocs

sphinx_rtd_theme

，您可以在

page.html

文件夹中创建的

_source/_templates/

模板扩展文件中轻松添加来自 algolia 文档的 CSS 链接和 Javascript 片段（见下文）。可能需要在您的设置的

conf.py

中注册此文件夹！

将此添加到您的

conf.py

的现有位置：

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

和

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

当我完成集成时，我可能会带着更详细的分步指南回到这里。

示例 config.json:

{
  "index_name": "yourindexname",
  "start_urls": [
    "https://replaceme.com"
  ],
  "stop_urls": [
    "https://replaceme.com/omit"
  ],
  "selectors": {
    "lvl0": ".section h1",
    "lvl1": ".section h2",
    "lvl2": ".section h3",
    "lvl3": ".section h4",
    "lvl4": ".section h5",
    "lvl5": ".section h6",
    "text": ".document p, .document li"
  },
}

更多信息：https://community.algolia.com/docsearch/config-file.html

这会在

custom.css

文件夹中添加 algolia CSS 和

_source/_static/

文件以覆盖样式。片段来源请参阅https://community.algolia.com/docsearch/dropdown.html

示例

page.html

模板：

{% extends "!page.html" %}

{% set css_files = css_files + ["https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css", "_static/custom.css"] %}

{% block footer %}
<script
src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script>
docsearch({
  // Your apiKey and indexName will be given to you once
  // we create your config. The appId value is missing in the first 
  // version of this example and in the algolia community doc 
  // until today (5th march of 2019).
  appId: '<your-app-id>',
  apiKey: '<yourkey>',
  indexName: '<yourindex>',
  // Replace inputSelector with a CSS selector
  // matching your search input
  inputSelector: '#rtd-search-form input[type=text]',
  // Set debug to true if you want to inspect the dropdown
  debug: true
});
</script>

{% endblock %}

ToDo：测试 algolia 社区文档的链接

提示：您可以通过将此样式添加到您的

custom.css

文件来测试输入选择器是否有效：

#rtd-search-form input[type=text]{
    background-color: #c51919; /* red */
}

Answer 2

更新至https://stackoverflow.com/a/54960623/1081006：

Algolia Docsearch API 已重写，现在是 V3。 V2 遗留功能有限，但对 V2 的官方支持已于 2020 年结束。

我们最近更新了上述示例中的内容，但无法让爬虫在 Python 2.7 下再次运行（预计这是由于 Python 2 将于 2020 年 EOL）。

我们可以使用Python3.8和更高版本的3.11重新安装爬虫，因为最新的代码兼容python 3。 https://github.com/algolia/docsearch-scraper。

爬虫可以更新 Algolia 的索引，但旧的 v2 Dropdown 现在拒绝工作。它生成了查找结果，但下拉链接内没有显示任何内容。

对于 Sphinx 前端，我们删除了下拉列表的旧版自定义集成，并从

https://github.com/algolia/sphinx-docsearch

切换到新的 Sphinx-doc 扩展 sphinx_docsearch。

v3 下拉菜单现在开始工作，但结果无法寻址并滚动到内容内的锚点。类似于常规 Sphinx 文档搜索的糟糕体验。

问题的根源是 Algolia 抓取的 Sphinx-doc HTML 中切换到 HTML5 部分标记。

我们更新了部分选择器中的

config.json

文件，删除了带有点前缀的类标记，并使用标签名称切换到 HTML5 部分标记，以反映最新版本的 Sphinx 和 readthedocs 主题中的最新 HTML 标记。

  "selectors": {
    "lvl0": "section h1",
    "lvl1": "section h2",
    "lvl2": "section h3",
    "lvl3": "section h4",
    "lvl4": "section h5",
    "lvl5": "section h6",
    "text": ".document p, .document li, .document ol, .document dt, .document dd"
  },

如果您使用手动生成的目录树并通过递归膨胀索引获得双重结果，请将其添加到末尾的

config.json

中：

  "selectors_exclude": [
    "[class^='toctree']"
  ],

您可以在 https://userguide.present4d.com/en

观看并测试结果