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模块的其他后续安装使其工作。

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

我们成功为Sphinx文档编制了索引，并运行.docsearch playground命令打开了一个测试Web服务器，该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 */
}

狮身人面像文档|它可以支持Algolia的文档搜索吗

1 个答案: