狮身人面像文档 |能支持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 和额外的 post 安装缺少的 dotenv 让它工作模块。

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

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

我们使用 readthedocs sphinx_rtd_theme，您可以在创建的 page.html 模板扩展文件中轻松添加来自 algolia 文档的 CSS-链接和 Javascript 片段_source/_templates/ 文件夹（见下文）。此文件夹可能需要在您的设置 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 文件来覆盖样式。片段的来源参见 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 %}

待办事项：测试 algolia 社区文档的链接

提示：您可以通过将此样式添加到您的 custom.css 文件来测试输入选择器是否有效：

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

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

Sphinx Docs | Can it support Algolia's Doc Search

python-sphinx

algolia