nikkie-ftnextの日記

イベントレポートや読書メモを発信

sphinx-revealjsで作ったスライドをGitHub Pagesで公開する

GitHub Actions Sphinx

はじめに

聞いて聞いて！ nikkieです。

先日以下のように書きました。

sphinx-revealjsいいと思うので、皆さんに使ってほしく、筆を進めねば・・

https://nikkie-ftnext.hatenablog.com/entry/yapc-japan-online-2022-awesome-talks#fn:5

こちらを実現させていきます。
まずは一番単純なトピックから。
sphinx-revealjsで作ったスライドをGitHub Pagesで公開する方法を共有します！

ちなみに私の登壇資料は、2021年からsphinx-revealjs × GitHub Pagesという組合せです！1

目次

TL;DR（sphinx-revealjsで作ったスライドをGitHub Pagesで公開する方法）

  • sphinx-revealjs作者のattakeiさんが実はすでにまとめているんです！（こちらを見てください）
  • このブログで付加できる価値は、より簡単に公開できる ように自作したアクション ftnext/action-push-ghpages の紹介です
  • GitHub Actions設定例

前提：Sphinxとは

Python製のライブラリで、ドキュメンテーションツールです。
reStructuredText（reST。拡張子は.rst）形式で記述すると、あれよあれよという間にドキュメントができあがります（まるで魔法！）

過去のみんなのPython勉強会2でも特集しました。3
詳しく知りたい方はアーカイブをどうぞ！

このSphinxでなんとプレゼンテーションに使うスライドも作れちゃうんです！！

attakeiさんによる『Sphinxでもプレゼンテーション』

sphinx-revealjsの紹介やプレゼンテーションの作り方、より使いこなすためのtipsやGitHub Pagesでの公開方法はattakeiさんのまとめに譲ります。
TL;DRで紹介したリンク先をぜひ読んでみてください！（本当にオススメなので、同じリンクを再掲しておきます）

Python製ドキュメンテーションビルダーSphinxを用いて、プレゼンテーションをしてみませんか？
この本は、Sphinxの拡張を使ってreStructuredTextからReveal.jsのプレゼンテーションを生成するハンドブックです。

私はSphinxが手に馴染んでいるので、「Sphinxでスライド作れるの、最高じゃん！」って感じですね。

sphinx-revealjsでスライドが作れる仕組み（概要）

スライドが作れる仕組みには、Reveal.jsというJavaScriptのライブラリも一役買っています。

  • スライドの内容をreSTで書く
  • ➡️ sphinx-revealjsがreSTをHTMLに変換（Reveal.jsに沿った形式）
  • ➡️ 変換されたHTMLをブラウザで開くと、Reveal.jsによってスライドとして表示されます！

つまり、スライドはHTMLなんですね。
そして、GitHub PagesはHTMLなどの静的ファイルをホストできるので、sphinx-revealjsで作ったスライド（HTML）を公開できます！

ftnext/action-push-ghpages を使って、より簡単に公開できます！

attakeiさんのまとめによると、GitHub Pagesとしての公開には maxheld83/ghpages を使います。

      - name: Deploy to GitHub Pages
        uses: maxheld83/ghpages@v0.2.1
        env:
          BUILD_DIR: build/revealjs
          GH_PAT: ${{ secrets.GH_PAT }}

${{ secrets.GH_PAT }}は、PATと呼ばれるトークンを作ってリポジトリに設定する必要があります。

これまでの素振り（後述）から、「このトークンって作る必要ないんじゃ？」と思い至りました。
maxheld83/ghpages@v0.2.1 を参考に、PATを作らずにGitHub Pagesとして公開できる ftnext/action-push-ghpages を実装しました。

ftnext/action-push-ghpages を使うと、以下のように書き換えられます。

      - name: Deploy to GitHub Pages
        uses: ftnext/action-push-ghpages@v1.0.0
        env:
          build_dir: build/revealjs
          github_token: ${{ secrets.GITHUB_TOKEN }}

${{ secrets.GITHUB_TOKEN }} は、GitHub Actionsを有効にするとリポジトリにインストールされるGitHub Appのアクセストークンです4。
これは設定不要で使えます。

アクションを自作して、PATを作る一手間を解消しました。
いいなと思ったら ftnext/action-push-ghpages を使ってみてください！

裏話：PATがいらないと気付いたきっかけ

git remote set-urlは要らない？ に関係して調べたところ、${{ secrets.GITHUB_TOKEN }}でもコミットをpushできそうだと分かりました。
この仮説を元に実装してみたのが ftnext/action-push-ghpages です。

未検証ですが、maxheld83/ghpages でもPATの代わりに${{ secrets.GITHUB_TOKEN }}を使えるかもしれません。

終わりに

sphinx-revealjsで作ったスライド（HTMLファイル）をGitHub Pagesで公開する方法を紹介しました。

基本はattakeiさんのまとめに沿っていただき、GitHub Pagesに公開するActionだけ ftnext/action-push-ghpages を使ってみてください！
私の登壇資料リポジトリの例も最後においておきます（TL;DRと同じリンク先です）

発表資料はプレーンテキストで書いて省力化すると、アウトプットが捗りますよー📣5

この記事は、以下のツイートを記事に書き上げたものになります。

  1. 2021 ➡ 2022でいくつかカイゼンしているのですが、それは追って共有していきます↩
  2. イベントレポート | オンライン開催のみんなのPython勉強会#58（Sphinx回）にスタッフ参加しました（配信まわり編） #stapy - nikkie-ftnextの日記↩
  3. 過去にSphinxのtipsを紹介した記事もあります Sphinxでクロスリファレンスを機能させるためには、includeするファイルをrst以外の拡張子にすべきと身をもって学びました - nikkie-ftnextの日記↩
  4. When you enable GitHub Actions, GitHub installs a GitHub App on your repository. The GITHUB_TOKEN secret is a GitHub App installation access token. ref:https://docs.github.com/ja/actions/security-guides/automatic-token-authentication#about-the-github_token-secret↩
  5. 経験者談（N=1）。LT王子の秘密を今回明かしました！↩