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

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

View Slide

イントロ
🟦 >
🟦 >
🟦

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

-> NEXT ->

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

HTMLプレゼンテーション用ライブラ
リ
Google I/O 2012 slide
Go talks
Impress.js
Reveal.js
Remark
(more...)

View Slide

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

View Slide

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

View Slide

SphinxとReveal.js
☑ > ☑ >
➡

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

sphinx-revealjs
このスライド1枚目のサンプル(ソース)
================================
================================
:Date: 2021/1/24
:Author: `Kazuya Takei `_
:Event: `July Tech Festa 2021 winter `_
:Hashtag: `#jtf2021w_d `_
.. include:: _sections/introduction.rst

View Slide

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


Date
2021/1/24

Author

Event
Hashtag

View Slide

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

View Slide

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

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

まとめ
☑ > ☑ > ☑

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

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

attakei

More Decks by attakei

Other Decks in Programming

Featured

Transcript