オンラインドキュメントと日本語全文検索

まとめ

  • 日本語検索に対応している Meilisearch を採用した
  • ドキュメントスクレイパーの実行は GItHub Actions (Self-hosted Runner) を採用した
  • 自社 Sphinx テーマの検索バーへ組み込む

ドキュメントの重要性

企業製品にとってドキュメントはとても重要です。自社のようなミドルウェア製品、かつクローズドソースの場合はドキュメントがすべてになります。自社でもドキュメントにはかなり力を入れています。

Algolia を検討

検索 SaaS といえば https://www.algolia.com/ です。最初はこれを使おうと思っていたのですが、日本語がどうなのかがいまいちわからなかったというのがあります。また、残念ながら多機能すぎて検証するまでの距離も長いです。

Meilisearch を検討

いろいろ調べていたら辿り着いたのが Meilisearch (ちなみにメイリサーチと発音するようです、YouTube で中の人の発音を確認するかぎり)です。

Meilisearch を検証

検索エンジンで一番重要なのが「日本語への対応」です。何でもかんでも日本語に対応しているわけではありません。海外のドキュメントサービスなんて基本日本語に対応していません。

Meilisearch を採用

Meilisearch はプライベートベータでクラウドサービスを展開しているのですが、残念ながら日本リージョンがないことから見送りました。

docs-scraper 実行には GitHub Actions (Self-hosted runner) を採用

docs-scraper はドキュメントに対して定期実行する必要があります。ドキュメントが変わったら検索インデックスも変更する必要があります。

on:
push:
paths-ignore:
- '**.md'
branches: [ "main" ]
pull_request:
branches: [ "main" ]
workflow_dispatch:schedule:
# JST は 2:00 は UTC の 17:00
# 1-5 で 月曜日から金曜日
- cron: '0 17 * * 1-5'
jobs:
docs-scraper:
runs-on: [self-hosted, linux, x64]
strategy:
max-parallel: 1
matrix:
config: [sample1.json, sample2.json]
steps:
- uses: actions/checkout@v3
- name: Run scraper
env:
HOST_URL: ${{ secrets.MEILISEARCH_HOST_URL }}
API_KEY: ${{ secrets.MEILISEARCH_API_KEY }}
CONFIG_FILE_PATH: ${{ github.workspace }}/${{ matrix.config }}
run: |
docker run -t --rm \
--network host \
-e MEILISEARCH_HOST_URL=$HOST_URL \
-e MEILISEARCH_API_KEY=$API_KEY \
-v $CONFIG_FILE_PATH:/docs-scraper/config.json \
getmeili/docs-scraper:latest pipenv run ./docs_scraper config.json
Self-hosted な GitHub Actions 経由で doc-scraper が動いてる

動作

実際に動かしてみると期待以上の結果でした。サーバ通信が発生しているとは思えない速度、そして雑に解析を設定したと思えない精度。

docs-scarper でインデックスを作成し docs-searchbar.js で検索している様子

Sphinx テーマに docs-searchbar.js を組み込む

Sphinx 用の自社 テーマを持っているため、これの検索部分を Meilisearch が用意している docs-searchbar.js に置き換えてしまえばもう終わりです。

import docsSearchBar from 'docs-searchbar.js'

docsSearchBar({
hostUrl: 'https://meilisearch.example.com/',
apiKey: 'xxx',
indexUid: 'doc',
inputSelector: '#search-bar-input',
})
html_theme_options = {
'meilisearch': True,
'meilisearch_api_key': 'xxx',
'meilisearch_host_url': 'https://meilisearch.example.com/',
'meilisearch_index_uid': 'doc'
}
Sphinx テーマ + Meilisearch docs-searchbar.js over HTTP/3

タイポ耐性

ライセンスをライスンスと打ち間違えてみた

雑感

ドキュメントの日本語全文検索はとにかく難しいので手を出してはならぬという考えが強かったのですが、今回の Meilisearch と Sphinx の組み合わせはとても満足できる結果になりそうです。

--

--

Erlang/OTP / 時雨堂 / WebRTC / E2EE / WebTransport

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
V

V

Erlang/OTP / 時雨堂 / WebRTC / E2EE / WebTransport