Dash for mac 向けに Optuna ドキュメントの docset 変換を自動化してみた


(更新:2021-12-22)Optuna のドキュメントが Dash アプリ内から直接ダウンロードできるようになりました!

0. はじめに

コードを書く時にドキュメントを参照することは多々あると思うのですが、こんな経験をしたことはないでしょうか?

「ドキュメントを見たいけどにネットに繋げない...」
「ググっても見たいドキュメントに辿り着くまでに時間がかかる...」

この記事ではそんな時に役立つ Dash for mac というアプリと、Optuna のドキュメントをこのアプリ用に変換する作業を自動化した話をご紹介します。

1. Dash for mac とは?

Dash for mac はオフラインでドキュメントの検索・閲覧ができる mac 用アプリです。

オフラインで検索ができる という部分が重要で、読みたいドキュメントに辿り着くまでの時間をかなり削減できます。

実際の操作例が以下になります。グローバルショートカットでどこからでも呼び出せるのも推しポイントです。

Dash を使ってドキュメントを閲覧するためには、ドキュメントを docset というフォーマットに変換されている必要があります。

デフォルトでかなり多くのドキュメントがサポートされている他、他のユーザーが変換したものを共有する仕組みもあるので、有名なライブラリはある程度網羅されています。

自分が探した範囲では Dash 用の Optuna ドキュメントは提供されていなかったので、それなら自分で作ろう!というのがこの取り組みの始まりでした。

ちなみに、このアプリは $29.99 とややお高めですが、(たしか)一ヶ月くらいの無料トライアル期間もあるのでぜひ一度試してみて下さい!

2. Optuna とは?

Optuna はブラックボックス最適化向けのオープンソースのソフトウェアです。

最もポピュラーな使い方は、機械学習モデルのハイパーパラメータ最適化だと思いますが、自分好みのコーヒーの淹れ方を探すために活用されている方もいらっしゃいます。

3. Optuna ドキュメントの docset への変換

Sphinx で生成される HTML ドキュメントの場合、doc2dash というモジュールを使うと簡単に変換できます。

今回は自動化ということで、「Optuna の最新リリースがあったら docset に変換しそれを自分のレポジトリに push する」という作業を GitHub Actions で実行しました。コピペするにはやや長くなってしまうので、興味のある方は以下のリンクからご参照下さい。

この workflow は、以下の3つの job で構成されています。

  • fetch Optuna の最新リリースを GitHub API 経由で取得 & 自分のリポジトリのバージョンを取得
  • build 最新リリースが自分のバージョンより新しければ HTML ドキュメントを生成
  • docset HTML ドキュメントを docset に変換 -> 自分のリポジトリにバージョン情報を併せて push

Github Actions の schedule トリガー を使うことで、一日に一回、上のフローを実行するように設定しています。

3.1 参考情報

Optuna の HTML ドキュメントを生成する部分は公式レポジトリの workflow を参考にしました。
https://github.com/optuna/optuna/blob/master/.github/workflows/sphinx-build.yml

それ以外のロジック(どうやってバージョン情報を取得・保持するかなど)はこちらのリポジトリを参考にしました。
今回の目的と同様、AWS-CLI のドキュメントを docset 自動変換する workflow を組んでいらっしゃる方です。
https://github.com/roberth-k/dash-docset-aws-cli

4. Dash で Optuna のドキュメントを参照するには(更新:2021-12-22)

上の方法で生成した docset が Dash 公式の User Contribution レポジトリ にマージされました 🎉

これにより、Dash のアプリ内から直接ドキュメントのインストールが可能になります。Dash > Preferences > Downloads の検索バーで "Optuna" と入力すると、ダウンロード可能なドキュメントが表示されるので、Download ボタンを押せばOKです!

以下のように、Dash アプリから Optuna のドキュメントを参照できるようになりました!

今回は手動で User Contribution レポジトリへの PR 作成を行いましたが、このあたりも半自動化できると嬉しいなと思っています。

本記事は以上となります。
最後までご覧頂き、ありがとうございました!