斯芬克斯文档 |能支持Algolia的Doc Search吗

Question

我想知道是否有人知道 Algolia 的文档搜索免费服务是否可以集成到 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 模块的额外安装后使其工作。

经过一些摆弄后，我根据

config.json

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

./docsearch bootstrap

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

我们成功地索引了 Sphinx-Documentation 并运行

.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

是的，您可以成功地将 Algolia 集成到您的 Sphinx 文档中。我们已将其集成到我们的开源 Sphinx 文档中。 https://docs.determined.ai/latest/ https://github.com/determined-ai/determined/tree/master/docs