Python Monthly Topics

Python製静的サイトジェネレーターSphinxでWebサイトを構築して公開

鈴木たかのり@takanoryです。今月の「Python Monthly Topics」では、Python製の静的サイトジェネレーターSphinxを使用してWebサイトを構築し、テーマを適用、外部へ公開する流れについて紹介します。後半ではSphinxの便利な拡張機能を紹介し、Webサイトをより便利にしていきます。

Markdownでドキュメントを書くだけで、きれいなWebサイトが簡単に公開できるので、ライブラリのドキュメントなどでもよく使われています。

Sphinxとは

SphinxはPython製の静的サイトジェネレーターです。静的サイトジェネレーターとは、Markdown等の軽量マークアップのテキストファイルから、静的なWebサイトを生成するアプリケーションのことを言います。Python製の静的サイトジェネレーターにはSphinxを含め以下のツールなどがあります。

他のプログラミング言語では、Go製のHugoやRuby製のJekyllなどがよく知られていると思います。

Sphinxの特徴

Sphinxは静的なWebサイト生成だけでなく、ドキュメントを作成することも目的としています。そのため、Sphinxでは1つのテキストファイルからHTMLだけでなく、PDF(LaTeX経由で作成)やePubなどの文書、書籍向けのフォーマットも生成できます。

また、さまざまな拡張機能が利用できます。本記事ではSphinxのおすすめの拡張機能についても紹介します。

Sphinxを使用しているサイト⁠書籍

Sphinxを使用しているサイトをいくつか紹介します。まず、Pythonの公式ドキュメントはSphinxで記述されています。元となるファイルはGitHubのCPythonリポジトリの中にあります。なお、公式ドキュメントの翻訳はTransifexという別サービスで行っています。興味のある方はPython Monthly Topicsの過去記事を参照してください。

Sphinxは多くのPython公式のドキュメントや、各種Python製ライブラリの公式ドキュメントでも採用されています。以下にいくつか例をあげます。

また、前述のようにSphinxは文書、書籍向けのフォーマットも生成できるため、書籍の執筆でも使われています。以下はSphinxで執筆された書籍の例です。ちなみに、Python Monthly Topicsの下書きもSphinxで執筆しています。

Sphinxの特徴や事例を把握したので、さっそくインストールして使ってみましょう。

Sphinxをインストールして手元で確認

まずはSphinxをインストールして、手元の環境でWebサイトを確認するところまでの手順を紹介します。

GitHubリポジトリの準備⁠Sphinxのインストール

GitHubで空のリポジトリを作成してからPCにcloneします。あとでこのリポジトリを使用して、Sphinxのドキュメントを外部サイトに公開します。以下のサンプルのリポジトリにはこの記事で設定した内容、ドキュメントが入っています。差分を確認するとどのような変更が入ったかわかりやすいと思います。実際に手元で実験する場合は自分で空のGitHubリポジトリを作成してください。

リポジトリをclone
% git clone https://github.com/takanory/gihyojp-sphinx-sample
% cd gihyojp-sphinx-sample

次にvenvモジュールを使用して仮想環境を作成し、Sphinxをインストールします。

Sphinxをインストール
% python3.12 -m venv env
% . env/bin/activate
(env) % pip install sphinx

Sphinxをインストールするとsphinx-quickstartコマンドが使えるようになるので、コマンドを実行して初期ファイルを作成します。プロジェクト名、著者などを指定すると初期ファイルが作成されます。

sphinx-quickstart コマンドを実行
(env) % sphinx-quickstart
> Separate source and build directories (y/n) [n]: y
〈省略〉
> Project name: Gihyojp Sphinx Sample
> Author name(s): takanory
> Project release []: 
〈省略〉
> Project language [en]: ja
% ls    # ファイルを確認
LICENSE		README.md	env		source
Makefile	build		make.bat

ここでmake htmlコマンドを実行すると、HTMLファイルがbuild/html/フォルダー以下に生成されます。index.htmlファイルをWebブラウザで開くと、結果が確認できます。

make htmlコマンドを実行してHTMLをビルド
(env) % make html
(env) % open build/html/index.html 
ビルドした結果が確認できた
ビルドした結果が確認できた

この状態で初期ファイル群をコミットしてプッシュします。以降、このように変更するたびにコミット、プッシュしてGitHub上で差分がわかるようになっています。ぜひ参考にしてください。

この状態のファイルをコミット
(env) % pip freeze > requirements.txt
(env) % git add .
(env) % git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   Makefile
        new file:   make.bat
        new file:   requirements.txt
        new file:   source/conf.py
        new file:   source/index.rst

(env) % git commit -m "GitHubリポジトリの準備、Sphinxのインストール"
(env) % git push

差分は以下で確認できます。

ドキュメントを編集⁠設定をカスタマイズ

次にドキュメントを少し書いて、Sphinxの設定も少しカスタマイズします。まずはドキュメントファイルの「source/index.rst」を書き換えます。SphinxではデフォルトではreStructuredTextという軽量マークアップ言語で記述します。ここでは、以下のようにドキュメント全体を書き換えます。

source/index.rst
gihyo.jp記事のSphinxサンプル
============================
このドキュメントは、gihyo.jpのPython Monthly Topics(https://gihyo.jp/list/group/Python-Monthly-Topics)でのSphinx記事のサンプルドキュメントです。

* 箇条書き
* 箇条書き

.. code-block:: python

   for i in range(100):
       print(i)

なお、本記事ではreStructuredText記法について解説はしません。興味がある方は以下のドキュメントを参照してください。

続いて設定ファイルであるsource/conf.pyを編集します。まずはテーマを変更します。Sphinxには複数のテーマが組み込まれており、デフォルトではalabasterテーマが指定してあります。conf.pyのhtml_theme変数の値を変更してここではbizstyleを指定します。なお、組み込みテーマの一覧はHTML Themingのページで確認できます。

source/conf.pyでテーマを変更
html_theme = 'bizstyle'

また、ドキュメントにロゴ画像を指定します。Python Monthly Topicsのロゴ画像を使用します。ダウンロードした画像をsoruce/_static/logo.pngに配置し、conf.pyに以下の記述を追加します。

source/conf.pyにロゴの指定を追加
html_logo = "_static/logo.png"

ここで再度make htmlコマンドを実行してindex.htmlを表示すると、ドキュメントの内容、HTMLテーマが変更、ロゴ画像が追加されていることが確認できます。

ドキュメント、テーマ変更、ロゴを追加
ドキュメント、テーマ変更、ロゴを追加

Markdownでドキュメントを書く

GitHub、QiitaなどMarkdownで記述できるサービスは多いため、Markdown記法に慣れている人も多いと思います。SphinxではMyST Parserという拡張機能を導入することにより、Markdownを扱えるようになります。MySTはMarkedly Structured Textの略で、Markdownを拡張してreStructuredTextと同じような機能を提供しています。MySTの拡張記法については以下の公式サイトを参照してください。

まず。MyST Parserをインストールします。requirements.txtファイルも更新しておきます。

Myst Parserをインストール
(env) % pip install myst-parser
(env) % pip freeze > requirements.txt

次にsource/conf.pyにMyST Parserを使用するための設定を追加します。extensions変数のリストに拡張機能名を追加するのみです。

source/conf.pyでMyST Parserを有効化
extensions = ["myst_parser"]

これで拡張子が.mdのファイルの場合は、MyST Parserが処理するようになります。source/index.rstを削除してsource/index.mdを追加します。

source/index.md

# gihyo.jp記事のSphinxサンプル

このドキュメントは、gihyo.jpの[Python Monthly Topis](https://gihyo.jp/list/group/Python-Monthly-Topics)でのSphinx記事のサンプルドキュメントです。
Markdownで書いてます。

* 箇条書き
* 箇条書き

```python
for i in range(100):
    print(i)
```

make htmlを実行し、Markdownのドキュメントからビルドできていることを確認します。

Markdownからドキュメントをビルド
Markdownからドキュメントをビルド

サードパーティーのテーマを利用

Sphinxのテーマには組み込みだけでなく、サードパーティーのテーマがあります。サードパーティーのテーマもインストールして使用できます。Sphinx Themes Galleryにはさまざまなテーマがあるので、好みのテーマを探してみてください。

ここでは最近筆者が気に入っているFuroというテーマを使用します。他にRead the DocsSphinx Book Themeも使われているサイトが多く、おすすめです。

Furoをインストールし、requirements.txtを更新します。

Furoをインストール
(env) % pip install furo
(env) % pip freeze > requirements.txt

次にsource/conf.pyでテーマをFuroに変更します。また、html_theme_options変数にGitHubのリポジトリ情報を設定すると、ドキュメントから直接GitHub上のファイルを参照できるのでおすすめです。

source/conf.pyでテーマをFuroに変更
html_theme = 'furo'
〈省略〉
html_theme_options = {
    "source_repository": "https://github.com/takanory/gihyojp-sphinx-sample/",
    "source_branch": "main",
    "source_directory": "source",
}

make htmlを実行すると以下のようにテーマが変わります。画面右上のペンのアイコンをクリックすると、GitHubのページに遷移します。

Furoテーマを適用
Furoテーマを適用

あとはドキュメントを書き進めたり、ファイルを追加したりと執筆を進めたらmake htmlで結果の確認を繰り返します。ドキュメントの具体的な書き方についてはMyST ParserまたはreStructuredTextのドキュメントを参照してください。

Read the DocsでWebサイトを公開

ここまではドキュメントはPCのローカルにしか存在しませんでした。ここからの手順で作成したドキュメントをインターネット上に公開し、誰でもアクセスできるようにしていきます。

アカウントを作成

Sphinxのドキュメントをホストするサービスはいくつかありますが、ここではRead the Docsを使用します。Read the DocsはSphinxとMkDocsに対応した、静的サイトジェネレーターのドキュメントをビルドしてホスティングするサービスです。

アカウントが必要なのでSign upをクリックしてアカウントを作成します。Publicリポジトリで公開ドキュメントであれば無料の「Read the Docs Community」でアカウントを作成します。

Read the Docs Communityでアカウントを作成
Read the Docs Communityでアカウントを作成

アカウント作成時に「Sign up with GitHub」を選択し、自身のGitHubアカウントを使用してアカウントを作成します。GitHubにログインすると権限の許可を求められるので、内容を確認し「Authorize readthedocs」ボタンをクリックして権限を設定します。この権限を設定することにより、GitHubから自動でビルドできるようになります。

Read the DocsにGitHubへのアクセス権限を設定
Read the DocsにGitHubへのアクセス権限を設定

最後にメールアドレスを入力してアカウント作成は完了です。次にプロジェクトを設定します。

プロジェクトを追加

Read the Docsの画面で「Import a Project」をクリックし、リポジトリの一覧からビルド対象のリポジトリを選択します。ここでは言語は日本語なので「Japanese」を選択して「Next」をクリック、次の画面で「Finish」をクリックしてプロジェクトの追加は完了です。

「Your document is building」のリンクをクリックしてビルド状況を確認します。ここでは設定が足りていないため、ビルドに失敗しています。

動画 Read the Docsにプロジェクトを登録

プロジェクトがビルドできるようにするために設定ファイルを追加します。

設定ファイルを追加

現在の状態ではRead the Docsのビルドに失敗し、以下のようなエラー画面が表示されます。

ビルドの失敗画面
ビルドの失敗画面

エラーメッセージに「The required .readthedocs.yaml configuration file was not found at repository's root」とあるとおり、リポジトリのルートに.readthedocs.yamlという設定ファイルを配置する必要があります。以下の内容を記述してリポジトリにプッシュします。

.readthedocs.yamlファイルのサンプル
# 必須
version: 2

# OSとPythonバージョンを設定する
build:
  os: ubuntu-22.04
  tools:
    python: "3.12"

# source/ ディレクトリ以下のドキュメントをビルドする
sphinx:
  configuration: source/conf.py

# requirements.txtのパッケージをインストールする
python:
  install:
    - requirements: requirements.txt

なお、設定ファイルの詳細な記述内容については、以下のドキュメントを参照してください。

再度ビルドを実行すると、ビルドに成功します。画面右上の「View Docs」ボタンをクリックすると、ビルドされたHTMLを参照できます。

ビルドに成功
ビルドに成功

Read the Docsではビルドしたドキュメントを「リポジトリ名.readthedocs.io」というドメインで公開します。この場合はhttps://gihyojp-sphinx-sample.readthedocs.io/というドメインにドキュメントがホスティングされるようになりました。

インターネット上に公開された
インターネット上に公開された

以降はドキュメントを修正してリポジトリにプッシュすると、自動でドキュメントが更新されます。

Read the Docsでは独自ドメインなど、さまざまな設定が可能です。詳細は設定画面やRead the Docsのドキュメントを参照してください。

他のホスティングの選択肢

SphinxドキュメントをビルドしてデプロイできるサービスはRead the Docs以外にもいくつかあります。ここでは簡単に紹介します。詳細な手順は以下のSphinxのドキュメントを参照してください。

GitHub Pages

GitHub PagesはGitHubが提供する静的ホスティングサービスです。GitHubのリポジトリ上のHTMLファイルをホスティングできます。GitHub Actionsと組み合わせることで、GitHubへのプッシュ時に自動ビルドが実行できるようになります。

Cloudflare Pages

Cloudflare PagesはCloudflareが提供するJAMstackプラットフォームですが、Sphinxのホスティングにも対応しています。詳細な手順は以下のドキュメントを参照してください。

ただこの手順は少し古く、ビルドシステムを最新バージョンの2にすると、Python 3.7ではなくPython 3.10が使用できます。また、pipenv ではなく pip を使用するようになるためPipfileは不要になり、requirements.txtのみが必要となります。

ビルドの構成で以下のように記述するとビルドされます。

ビルド コマンド make html
ビルド出力ディレクトリ /build/html
ルート ディレクトリ /
プルリクエストのビルドコメント 有効

また、Cloudflare PagesとCloudflare ゼロトラストを組み合わせると、認証付きのページも作成できます。

Netlify

Netlifyも静的ホスティングサービスの1つです。ただし、NetlifyのPythonバージョンはPython 3.8のため、最新のSphinxが使用できません。

Sphinxをさらに拡張

SphinxのドキュメントがRead the Docsで自動的にビルドされれるようになりました。ここからは筆者おすすめの拡張機能を紹介します。

ぜひ拡張機能を上手に利用してドキュメントをよりよいものにしてください。サードパーティーの拡張機能は以下のページで探すことができます。

Sphinx内蔵の拡張機能

Sphinxにはあらかじめ含まれている拡張機能があります。一覧は以下のページにあります。

おすすめの拡張にsphinx.ext.todoがあります。sphinx.ext.todoはドキュメントにTodoを入れられる拡張機能です。機能を有効にするにはconf.pyのextensions"sphinx.ext.todo"を追加します。

source/conf.py でsphinx.ext.todoを有効化
extensions = [
    "myst_parser",
    "sphinx.ext.todo",
]

# TODOを有効にする
todo_include_todos = True

あとは任意のページに以下のように書いた項目がTODOとなります。

todoを記述
```{todo}
ソースコードを実際に動かして動作確認する
```

そしてトップページなどに以下のように書いておくと、その位置にすべてのTODOが表示されます。

todoの一覧を表示
```{todolist}
```

ドキュメントをビルドすると、以下のようにTODOの一覧が表示されます(ここでは1件だけですが⁠⁠。ドキュメントであとで書く、確認することをTODOにしておくと、把握がしやすく便利です。

sphinx.ext.todo機能でTODOが表示される
sphinx.ext.todo機能でTODOが表示される

sphinx-autobuild⁠ドキュメントを自動ビルド

sphinx-autobuildは、Sphinxのドキュメントが変更されたら、自動的にビルドをしてブラウザを再読み込みする拡張機能です。Sphinxでドキュメントを執筆するときには、エディターで執筆→make htmlを実行してビルド→ブラウザで再読みこみを繰り返します。この拡張機能を使うことで、エディターで編集して保存するだけで、あとの処理はsphinx-autobuildが実行してくれるようになります。

sphinx-autobuildをpipコマンドでインストールします。

sphinx-autobuildをインストール
(env) % pip install sphinx-autobuild

拡張機能をインストールするとsphinx-autobuildコマンドがインストールされるので、コマンドを以下のように実行します。デフォルトでは8000番ポートでWebサーバーが起動するので、Webブラウザで http://127.0.0.1:8000/ にアクセスすると、常に最新のドキュメントが表示されるようになります。ポート番号を変更したい場合は--port 8001のように指定してください。

sphinx-autobuildを実行
(env) % sphinx-autobuild source build/html
(env) % sphinx-autobuild source build/html --port 8001  # ポート番号を指定する場合

sphinx-copybutton⁠コードをクリップボードにコピー

sphinx-copybuttonは、ソースコードをクリップボードにコピーするボタンを追加する拡張機能です。

sphinx-copybuttonをpipコマンドでインストールし、source/conf.pyに拡張機能として追加します。

sphinx-copybuttonをインストール
(env) % pip install sphinx-copybutton
source/conf.pyでsphinx-copybuttonを有効化
extensions = [
    "myst_parser",
    "sphinx.ext.todo",
    "sphinx_copybutton",
]

拡張機能が有効になると、コードブロックの右上にコピーボタンが表示されます。コピーボタンをクリックすると、コードがクリップボードにコピーされます。

動画 sphinx-copybuttonでコードをコピー

sphinx-design⁠デザインコンポーネント⁠アイコンを追加

sphinx-designは、Sphinxのドキュメントでグリッドレイアウトやドロップダウン、タブといたデザイン用のコンポーネントを追加します。また、各種アイコンも追加します。この拡張機能を使うには、他と同様にpipコマンドでインストールし、source/conf.pyに拡張機能として追加します。

sphinx-designをインストール
(env) % pip install sphinx-design
source/conf.pyでsphinx-designを有効化
extensions = [
    "myst_parser",
    "sphinx.ext.todo",
    "sphinx_copybutton",
    "sphinx_design",
]

筆者はこの拡張機能を、Font Awesomeのアイコンをドキュメントで表示する用途で使用しています。Font Awesomeのアイコンを表示するには、source/conf.pyに以下の記述を追加します。またMaterial Iconsも使用できます。

source/conf.pyにFont AwesomeのCSSを追加
html_css_files = [
    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css"
]

ドキュメントに以下のように書くと、Font AwesomeとMaterial Iconsが使用できます。

リスト Font AwesomeとMaterial Iconsを記述
## Font Awesome

* {fab}`twitter` [@takanory](https://twitter.com/takanory)
* 私は{fas}`music` が好きで、{fas}`beer-mug-empty`も好きです。

## Material Icons

* {material-regular}`headphones`はBOSEを使っています
* {material-regular}`pets`にはフェレットを飼っています
アイコンが表示される
アイコンが表示される

sphinxext-opengraph: OGP(Open Graph Protocol)用のメタデータ⁠画像を生成

sphinxext-opengraphOGP(Open Graph Protocol)用のメタデータ、画像を生成する拡張機能です。これらの情報が適切に設定してあると、WebページをSNS等で共有したときに画像や説明文が適切に入るため、リンク先の内容がわかりやすくなります。

まずはpipコマンドでsphinxext-opengraphをインストールします。また後述するソーシャルカードの自動生成のために、Matplotlibもインストールします。

sphinxext-opengraphとMatplotlibをインストール
(env) % pip install sphinxext-opengraph matplotlib

そしてsource/conf.pyで拡張機能として追加し、いくつか設定を記述します。

source/conf.pyでsphinxext-opengraphを有効化し、設定を追加
extensions = [
    "myst_parser",
    "sphinx.ext.todo",
    "sphinx_copybutton",
    "sphinx_design",
    "sphinxext.opengraph",
]

# サイトURLとデフォルト画像を設定
ogp_site_url = "https://gihyojp-sphinx-sample.readthedocs.io/ja/latest/"
ogp_image = "https://gihyojp-sphinx-sample.readthedocs.io/ja/latest/_static/logo.png"

するとHTMLのヘッダーに以下のようにogタグが挿入され、SNS等でシェアしたときに画像や説明が入るようになります。

<meta property="og:title" content="gihyo.jp記事のSphinxサンプル" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://gihyojp-sphinx-sample.readthedocs.io/index.html" />
<meta property="og:site_name" content="Gihyojp Sphinx Sample" />
<meta property="og:description" content="このドキュメントは、gihyo.jpの Python Monthly Topis でのSphinx記事のサンプルドキュメントです。 Markdownで書いてます。 目次: sphinx.ext.todoのサンプル, sphinx-copybuttonのサンプル, sphinx-designのサンプル- Font Awesome, Material Icons.. TODOリスト:( 元のエン..." />
<meta property="og:image" content="https://gihyojp-sphinx-sample.readthedocs.io/ja/latest/_static/logo.png" />
<meta property="og:image:alt" content="Gihyojp Sphinx Sample" />
<meta name="description" content="このドキュメントは、gihyo.jpの Python Monthly Topis でのSphinx記事のサンプルドキュメントです。 Markdownで書いてます。 目次: sphinx.ext.todoのサンプル, sphinx-copybuttonのサンプル, sphinx-designのサンプル- Font Awesome, Material Icons.. TODOリスト:( 元のエン..." />

ソーシャルメディアカードの生成

sphinxext-opengraphのさらに強力な機能に、ソーシャルメディアカードの生成があります。この機能は、og:image用にページのタイトルや説明を埋め込んだ画像を、Matplotlibを使用して生成するというものです。機能の詳細は以下のページを参照してください。

ソーシャルメディアカードを生成するために、source/conf.pyに以下の設定を追加します。デフォルトのフォントは英語のみに対応しているため、Read the Docsのサーバーにデフォルトでインストールされている日本語に対応したフォントを指定します(環境により変わります⁠⁠。また、ローカルのmacOSやWindowsでの実行時にエラーにならないように、フォントの設定を変更するコードも入れておきます。

source/conf.pyにソーシャルメディアカード用の設定を追加
# ogp_imageオプションはコメントアウト
# ogp_image = "https://gihyojp-sphinx-sample.readthedocs.io/ja/latest/_static/logo.png"

# ソーシャルカード用の画像とフォントの設定
ogp_social_cards = {
    "enable": True,
    "image": "_static/logo.png",
    "font": "Noto Sans CJK JP",
}

# macOSとWindows用のフォント設定
if sys.platform == "darwin":
    ogp_social_cards["font"] = "Hiragino Maru Gothic Pro"
elif sys.platform == "win32":
    ogp_social_cards["font"] = "MS Gothic"

ソーシャルメディアカードが生成されると、ヘッダーのog:imageのURLが以下の様なランダムな文字列を含んだ画像ファイル名になります。

<meta property="og:image" content="https://gihyojp-sphinx-sample.readthedocs.io/_images/social_previews/summary_index_cda79cf9.png" />

各SNSで実際にどのように表示されるかを、www.opengraph.xyzというサイトにURLを入力して確認します。すると、以下のようにソーシャルカードが生成され、プレビューがわかりやすくなったことがわかります。

www.opengraph.xyzで結果をプレビュー
www.opengraph.xyzで結果をプレビュー

og:imageの画像は以下のような内容です。このような画像がページごとに生成され、それぞれタイトルや説明文が入ります(ロゴ画像とタイトルがかぶってしまってますが⁠⁠。

トップページのog:image画像
トップページのog:image画像

sphinx-comments⁠コメント機能を追加

Sphinx CommentsはSphinxのWebサイトにコメント機能を追加する拡張機能です。書籍のレビューやプレビュー版のWebサイトに対して、SphinxのWebページ上でコメントができるようになります。コメントの書き込み、保存する機能には外部サービスを使用しています。ここではHypothesisという、インターネット上の任意のページに注釈を付けられるサービスを使用します。

pipコマンドでsphinx-commentsをインストールし、source/conf.pyに設定を追加します。

sphinx-commentsをインストール
(env) % pip install sphinx-comments
source/conf.pyにsphinx-commentsの設定を追加
extensions = [
    "myst_parser",
    "sphinx.ext.todo",
    "sphinx_copybutton",
    "sphinx_design",
    "sphinxext.opengraph",
    "sphinx_comments",
]

# コメントをHypothesisでする
comments_config = {
   "hypothesis": True
}

拡張機能が有効になると、画面右上にコメントを表示する欄を開くためのアイコンが表示されます。また、ページ内を選択するとその箇所に対してコメントが書けます。

動画 sphinx-commentsでページにコメントを追加

なお、コメントを書き込むにはHypothesisのアカウントが必要となります。また、書き込んだコメントとURLはHypothesisサイト上で誰でも参照できるため、秘密の情報を書かないように注意してください。

sphinx-revealjs⁠プレゼンテーション資料を作成

sphinx-revealjsはSphinxのドキュメントからプレゼンテーション用のHTMLを生成する拡張機能です。内部的にはreveal.jsというJavaScriptのフレームワークを使用しています。

sphinx-revealjsを使用するにはpipコマンドでインストールしてsource/conf.pyに設定を追加します。

sphinx-revealjsをインストール
(env) % pip install sphinx-revealjs
source/conf.pyにsphinx-revealjsの設定を追加
extensions = [
    "myst_parser",
    "sphinx.ext.todo",
    "sphinx_copybutton",
    "sphinx_design",
    "sphinxext.opengraph",
    "sphinx_revealjs",
]

設定が完了するmake revealjsコマンドが使用できるようになります。コマンドを実行するとbuild/revealjs/フォルダにスライドのHTMLが生成されます。

make revealjsコマンドを実行
(env) % make revealjs

Webブラウザでbuild/revealjs/index.htmlを表示すると、以下のようなプレゼン資料が表示されます。第2レベル、第3レベルの見出し単位でスライドが作成されます。

生成されたスライドを表示
生成されたスライドを表示

具体的なスライドの表示イメージは公式ドキュメントの以下のスライドを参照してください。

なお、筆者は最近のプレゼン資料はすべてsphinx-revealjsで作成しています。ぜひ参考にしてみてください。

まとめ

本記事の前半ではSphinxを使ってMarkdownで書いたドキュメントからWebサイトを構築し、外部へ公開する流れについて紹介しました。そして後半ではSphinxをさらに便利にするおすすめの拡張機能を紹介しました。

本記事で紹介したSphinxや拡張機能の設定や使い方は、それぞれのほんの一部です。さらに詳細な設定や使い方については、それぞれの公式ドキュメントを参照してください。

また、筆者が出演しているYouTube PyCon JP TVで、本記事の一部の手順を実際にライブデモで見せている動画があります。実際にコマンドを入力して動作しているところ見た方がイメージが湧きやすい部分もあると思います。こちらも参考にしてみてください(20:42からライブデモをしています⁠⁠。

Sphinxの使いこなしについてはSphinx-users.jpの情報も参考になります。また、毎月イベントを開催しているので、そちらに参加してみると知見が得られるかも知れません。

ドキュメントを中心としたWebサイトを構築したいときには、ぜひSphinxにチャレンジしてみてください。

おすすめ記事

記事・ニュース一覧