sphinxcontrib-screenshot — ウェブサイトのスクリーンショットを簡単に埋め込めるSphinx拡張

Sphinxを使ってドキュメントを作成する際、ウェブサイトのスクリーンショットを掲載したい場面は多いでしょう。しかし手動でスクリーンショットを撮影し、適切なサイズにトリミングしたり画像ファイルを管理したりするのは手間がかかる作業です。 URLと画像サイズだけを指定したら、よしなに画像を埋め込んでほしいと思いませんか？

こういったスクリーンショット管理の手間を減らすためにsphinxcontrib-screenshotというSphinx拡張を作りました。このSphinx拡張を使えば、簡単な記述でウェブサイトのスクリーンショットをドキュメントに埋め込むことができます。

簡単な機能紹介

sphinxcontrib-screenshotは、以下の機能を提供します。

URL指定でスクリーンショットを自動撮影: URLを指定するだけで、Playwrightを用いて自動的にスクリーンショットを撮影します。
スクリーンサイズのカスタマイズ: width や height パラメータを指定してスクリーンショットのサイズを自由に調整できます。
キャプションの追加: caption パラメータで、スクリーンショットにキャプションを追加できます。
ページ操作の自動化: スクリーンショット撮影前に施したい操作をJavaScriptでディレクティブ本文に記述できます。
ローカルファイルのサポート: URLだけでなく、ローカルファイルのパスを指定してスクリーンショットを撮影することも可能です。

導入方法

sphinxcontrib-screenshotはPyPIで公開されており、以下のコマンドで簡単にインストールできます。ふたつめのコマンドは、Playwrightで使うブラウザをインストールするためのコマンドです。

pip install sphinxcontrib-screenshot
playwright install

次にSphinxプロジェクトの conf.py に sphinxcontrib.screenshot を追加します。

extensions = ["sphinxcontrib.screenshot"]

これで準備完了です。

使い方

Sphinxのソースファイル内で、 screenshot ディレクティブを使ってスクリーンショットを撮りたいウェブサイトのURLを指定します。

.. screenshot:: http://www.example.com

width や height パラメータでスクリーンショットのサイズを指定したり、 caption パラメータでキャプションを追加したりすることもできます。

.. screenshot:: http://www.example.com
   :width: 1280
   :height: 960
   :caption: これはwww.example.comのスクリーンショットです。

さらにスクリーンショット撮影前のページ操作をJavaScriptで記述して自動化することも可能です。

.. screenshot:: http://www.example.com

   document.querySelector('button').click();

もし共通化して事前に実行したいJavaScriptコードがある場合には conf.py に screenshot_init_script として記述することもできます。

さいごに

sphinxcontrib-screenshotはApache License 2.0ライセンスのオープンソースプロジェクトです。詳細情報やソースコードは、以下のGitHubリポジトリで公開されています。

GitHub: https://github.com/tushuhei/sphinxcontrib-screenshot
PyPI: https://pypi.org/project/sphinxcontrib-screenshot/

sphinxcontrib-screenshotは、Sphinxドキュメントにウェブサイトのスクリーンショットを簡単に埋め込むことができる便利なSphinx拡張です。ぜひ導入して、ドキュメント作成を効率化してみてください！