$30 off During Our Annual Pro Sale. View Details »

プレゼン?それもSphinxで出来るよ -ドキュメントツールSphinxのちょっと変わった利用法- / You can presentation too by Sphinx!

attakei
February 13, 2021

プレゼン?それもSphinxで出来るよ -ドキュメントツールSphinxのちょっと変わった利用法- / You can presentation too by Sphinx!

July Tech Festa 2021 winterで発表した資料のPDF版です。
この資料はHTMLプレゼンテーションがベースのため、最新ではない可能性があります。
HTML版はこちら

attakei

February 13, 2021
Tweet

More Decks by attakei

Other Decks in Programming

Transcript

  1. プレゼン?それもSphinxで出来るよ
    -ドキュメントツールSphinxのちょっと変わった利用法-
    Date: 2021/1/24
    Author:
    Event:
    Hashtag:
    Kazuya Takei
    July Tech Festa 2021 winter
    #JTF2021w_d

    View Slide

  2. イントロ
    🟦 >
    🟦 >
    🟦

    View Slide

  3. CfPより
    推しテク=Sphinx 枠です
    ドキュメンテーション作成や技術書執筆
    にも使えるドキュメンテーションツー
    ル、Sphinx。 単純なHTML生成としてだ
    けではなく、プレゼンテーションにも使
    ってみませんか?
    Sphinxにおけるプレゼンテーションの事
    例を追いつつ、自作ライブラリの紹介な
    どを行いたいと思います。

    View Slide

  4. 自己紹介
    Kazuya Takei
    NIJIBOX Co., Ltd
    サーバーサイドエンジニア
    アーキテクト
    @attakei as 雑食系エンジニア
    and more
    Twitter
    GitHub

    View Slide

  5. 自己紹介
    July Tech Festa
    2018: WebUSBによって広がる、
    NFCを取り扱う世界
    2020: Web制作において、プレビ
    ューにあえてCloudRun(と
    Firebase)を使う
    2021w: プレゼン?それもSphinx
    で出来るよ (New!)

    View Slide

  6. 注意事項
    1. 今回は、個人エンジニアとしての推しテク紹介です。
    この推しテクは自身が社内用にも使ってたりします
    が、自分しか使ってません。
    2. スライド書いてたら、ほとんどコードが出てきません
    でした。

    View Slide

  7. 主に話すこと
    ゴール:「Sphinxでプレゼンテーションができる」
    Sphinxと普段の役割
    Sphinxとプレゼンテーション
    SphinxとReveal.js

    View Slide

  8. Sphinxと普段の役割
    ➡ >
    🟦 >
    🟦

    View Slide

  9. Sphinx
    3行で
    複数の出力形式に対応した
    拡張性の高い
    Python製ドキュメンテーションビルダー

    View Slide

  10. ドキュメンテーションビルダー
    ドキュメントのソースから
    ドキュメント間の相互参照
    階層構造の構築
    ソースコードハイライト
    etc
    を行い、ドキュメント全体を組み立てる
    SOURCES Sphinx DOCUMENT
    A
    TION

    View Slide

  11. Sphinxが取り扱うソース
    reStructuredText
    Markdown
    (etc)
    .rst
    .md
    Sphinx DOCUMENT
    A
    TION

    View Slide

  12. Sphinxが取り扱うビルド先
    HTML
    ePub
    PDF(LaTex)
    man
    (etc)
    SOURCES(.md , .rst) Sphinx HTML,EPUB
    PDF

    View Slide

  13. Sphinxを使ったサイト
    いっぱいある
    ... Python本体
    ... Python製Webアプリケーションフレームワーク
    ... Python製の数値計算ライブラリ
    ...その他、Pythonパッケージいっぱい
    Python documentation
    Django documentation
    NumPy Manual

    View Slide

  14. Sphinxを使ったサイト
    まだまだある
    ... Python製の構成管理ツール
    ... Python製のインスタンス初期設定ツール
    ... PHP製のデータベース操作Webアプリ
    Ansible documentation
    cloud-init Documentation
    phpMyAdmin documentation

    View Slide

  15. Sphinxを使ったサイト
    まだまだある
    ... 電子書籍管理ツール
    ... Linux向けアプリケーションパッケージャー
    ... 名前の通り
    calibre User Manual
    Flatpak
    Ubuntu packaging guide

    View Slide

  16. Sphinxを使った書籍
    (書籍執筆のどこかの工程でSphinxを使っているもの)
    Go言語による並行処理
    Pythonプロフェッショナルプログラミング第3版
    独学プログラマー
    エキスパートPythonプログラミング改訂2版
    仕事ではじめる機械学習

    View Slide

  17. -> NEXT ->

    View Slide

  18. Sphinxとプレゼンテーショ

    ☑ >
    ➡ >
    🟦
    … 対象者:プレゼン系ソフトウェアを使いたがらない方 /
    プレゼン資料もGit管理してみたい方

    View Slide

  19. プレゼン系ソフトウェアって?
    いわゆるこの辺を指します
    Microsoft PowerPoint
    Keynote
    Google スライド

    View Slide

  20. 「プレゼン系ソフト」を使わずにプレ
    ゼンをする
    HTMLでプレゼン
    PDFでプレゼン
    Unityでプレゼン
    ターミナルでTelnet接続したらプレゼン

    View Slide

  21. HTMLでプレゼンすると何がいいか
    主なメリット
    OSを選ばない
    ファイルをGit管理しやすい
    (デメリット)
    公開・共有にひと手間かかる
    ブラウザは選ぶ

    View Slide

  22. HTMLでプレゼンすると何がいいか
    1:OSを選ばない
    ブラウザベースの表示なので、端末も選ばない
    PC
    タブレット
    スマホ
    ただしブラウザ依存の実装した場合は要注意
    Chromeは新しすぎ
    IEは忘れる

    View Slide

  23. HTMLでプレゼンすると何がいいか
    2:ファイルをGit管理しやすい
    リソースが分離した状態なので、差し替えなどが比較
    的容易
    差分がわかりやすい(別テキストからHTMLを生成する
    場合に顕著)
    CI/CDしやすい(GitHub Pagesなど)

    View Slide

  24. Sphinxが取り扱うビルド先(再掲)
    HTML
    ePub
    PDF
    man
    (etc)

    View Slide

  25. Sphinxが取り扱うビルド先(再掲)
    HTML <= こっち
    ePub
    PDF
    man
    (etc)

    View Slide

  26. 「SphinxでHTMLプレゼンテーショ
    ン」を実現するには
    基本的には、
    なにかしらのHTMLプレゼン用ライブラリを準備して
    HTML+JSを出力するテーマ・拡張を用意する

    View Slide

  27. HTMLプレゼンテーション用ライブラ

    Google I/O 2012 slide
    Go talks
    Impress.js
    Reveal.js
    Remark
    (more...)

    View Slide

  28. HTMLプレゼンを使うためのSphinx拡
    張集
    hieroglyph
    sphinxjp.themes.gopher
    sphinxjp.themes.impressjs
    sphinxjp.themes.reveajs
    sphinxjp.themes.s6
    sphinx-revealjs

    View Slide

  29. -> NEXT ->
    ここからのメインは sphinx-revealjs

    View Slide

  30. SphinxとReveal.js
    ☑ > ☑ >

    View Slide

  31. Reveal.js
    多機能な、HTMLプレゼンテーション用のフレームワーク
    http://revealjs.com/

    View Slide

  32. こんなことができる
    縦横遷移による、ネストされたセクションの表現
    様々なページ遷移アニメーション
    PDFエクスポート機能
    プラグインによる拡張
    数式サポート
    シンタックスハイライト
    スピーカーノート
    Markdownソースの直接変換

    View Slide

  33. HTMLプレゼンを使うためのSphinx拡
    張集(再掲)
    hieroglyph
    sphinxjp.themes.gopher
    sphinxjp.themes.impressjs
    sphinxjp.themes.reveajs
    sphinxjp.themes.s6
    sphinx-revealjs <= 作った

    View Slide

  34. sphinx-revealjs
    作りました(最近、ver1.0に)
    Markdownプラグインに近い感覚で、RSTをReveal.js
    プレゼンにする拡張
    基本機能は揃ってる...はず
    階層によるネストされたセクション
    テーマの切り替え
    プラグインの呼び出し
    Reveal.jsと競合しない範囲で、既存のSphinx拡張を使
    い回せる
    https://github.com/attakei/sphinx-revealjs

    View Slide

  35. sphinx-revealjs
    このスライド1枚目のサンプル(ソース)
    ================================
    プレゼン?それもSphinxで出来るよ
    ================================
    -ドキュメントツールSphinxのちょっと変わった利用法-
    :Date: 2021/1/24
    :Author: `Kazuya Takei `_
    :Event: `July Tech Festa 2021 winter `_
    :Hashtag: `#jtf2021w_d `_
    .. include:: _sections/introduction.rst

    View Slide

  36. sphinx-revealjs
    このスライド1枚目のサンプル(HTML)

    プレゼン?それもSphinxで出来るよ
    -ドキュメントツールSphinxのちょっと変わった利用法-

    Date
    2021/1/24

    Author


    Event
    Hashtag

    View Slide

  37. sphinx-revealjs
    デモをどうぞ
    => https://attakei.github.io/sphinx-revealjs

    View Slide

  38. sphinx-revealjs
    デモから一部抜粋
    ===============
    sphinx-revealjs
    ===============
    :Based version: 1.0.0
    :Released: 2020-12-27
    Overview
    ========
    What is this?
    -------------
    Sphinx extension to build Revealjs presenta
    Features
    --------

    View Slide

  39. もう一歩変わった使い方
    「ドキュメンテーション」と「プレゼンテーション」
    をまとめて作成
    Qiita記事のスライドモード的な使い方
    https://github.com/attakei-sandbox/sphinx-
    revealjs-demo

    View Slide

  40. モチベーションの話
    欲しかったけど、軽く探して見つからなかった
    プラグイン開発
    コア部分は基本的にSphinxに任せてる
    「Reveal.jsとしてHTML出力させる」ためのこと
    だけ実装すれば良い
    ドッグフーディングの素材
    自分のLTのお供に
    Pythonパッケージングの素体に

    View Slide

  41. 発表してみた
    ある程度まともに動いたところで、SphinxCon JPに飛び込
    んでLTしてみました

    View Slide

  42. 発表してみた
    これ以降、細かい改良を進めつつ、自分の発表のベースと
    して積極的に利用しています
    PyCon JP 2019
    July Tech Festa 2020
    Pycon JP 2020
    July Tech Festa 2021 winter
    => 世界が広がっていく感じする

    View Slide

  43. 嬉しいこと
    地味にスターが増えてる
    海外のイベントで使われてた(最近だと国内でも)
    Issue/PRをもらえてて、英語の勉強になってる
    おまけ:これがきっかけで、Sphinxハッカソンに積極
    参加するように
    => 他の人の世界も少し広がっていく感じする

    View Slide

  44. まとめ
    ☑ > ☑ > ☑

    View Slide

  45. プレゼンはSphinxで出来ます
    Sphinxはドキュメンテーションビルダーだからこそ、
    プレゼンテーションもできます
    推しテクで色々やってたら、ちょっと自分の世界が広
    がりました
    他の人の世界もちょっと広がったみたいです
    sphinx-revealjsに興味がある方は、お試しとフィード
    バックお願いします
    🙇

    View Slide

  46. 参考情報集
    Sphinx関連
    Sphinx サイト
    Sphinx 日本ユーザー会
    Sphinx テーマ集

    View Slide

  47. 参考情報集
    sphinx-revealjs関連
    GitHubリポジトリ
    ドキュメント
    プレゼンテーションデモ
    変換サンプル

    View Slide

  48. 参考情報集
    その他
    ソースだけでなく、CI/CDのサンプルにどうぞ
    このスライドのソース
    NIJIBOX Co., Ltd

    View Slide