狮身人面像文档 |能支持Algolia的Doc Search吗

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，并使用 pipenv 和缺少的 dotenv 模块的附加后安装使其工作。

经过一番摆弄后，我使用了基于./docsearch bootstrap 命令输出的自定义config.json，将所有以“lvln”开头的行中出现的“FIXME”替换为“.section”，并将“FIXME”替换为以“text”开头的行和“.document”（参见下面的示例）。

我们成功地索引了 Sphinx 文档并运行 .docsearch playground 命令打开了一个测试网络服务器，该服务器立即提供了出色的结果。

我们使用 readthedocs sphinx_rtd_theme，您可以轻松地将 algolia 文档中的 CSS-Links 和 Javascript sn-ps 添加到创建到 _source/_templates/ 文件夹中的 page.html 模板扩展文件中（见下文）。此文件夹可能需要在您的设置的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

这会在 _source/_static/ 文件夹中添加 algolia CSS 和 custom.css 文件以覆盖样式。 sn-ps的来源见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 */
}