sphinx-revealjsの紹介

Based version:

3.0.1

Demo updated:

2022-11-13

基本的な説明

これはなにか

SphinxドキュメンテーションからReveal.jsプレゼンテーションを生成するための拡張ライブラリです。

主な機能

• reStructuredTextの文法構造からReveal.jsのセクション構造を生成

• セクションのカスタマイズ機能

• Reveal.js向けのプラグイン組み込み

• Sphinx拡張の利用

• 組み込みのテーマ切り替え

基本的な使い方

インストール

sphinx-revealjs はPyPIに登録されているため、pipコマンドで安定版のインストールが可能です

pip install sphinx-revealjs

セットアップ

conf.py を編集して拡張を有効にするだけで使えます。

extensions = [
    "sphinx_revealjs",
]

設定の調整なども可能です。細かい設定は ドキュメンテーション を参照してください。

ソースを作成

標準的なreStructuredText記法で作成してください。

My Reveal.js presentation
=========================

Agenda
------

* Author
* Feature

Author: Who am I
================

Own self promotion

Content
=======

ビルドする

sphinx-revealjs は専用のビルダーとして revealjs を提供しています。もしプレゼンテーションとして出力したい場合は、make revealjs と実行するだけで生成できます。

make revealjs

このプレゼンテーション自体も このソース から生成されています。

脚注

脚注記法を用いることが出来ます。内部拡張を利用することで、脚注の出力位置をスライド下部に調整することが出来ます。 [1]

reStructuredTextからReveal.jsへの変換

reSTの構造が、そのままReveal.jsのセクション構造に

Title
=====

First section
-------------

Content 1
^^^^^^^^^

Content 2
^^^^^^^^^

<section>
    <h1>Title</h1>
</section>
<section>
    <section>
        <h2>First section</h2>
    </section>
    <section>
        <h3>Content 1</h3>
    </section>
    <section>
        <h3>Content 2</h3>
    </section>
</section>

標準ディレティブが利用可能

Sub section
-----------

Content
^^^^^^^

.. image:: ./your-image.png

<section>
  <section>
     <h2>First section</h2>
  </section>
  <section>
     <h3>Content 1</h3>
     <img src="_images/your-image.png">
  </section>
</section>

Sphinx拡張によるディレクティブも利用可能

.. oembed:: \
https://twitter.com/attakei/status/1517152841550376961

reSTのコメント

Title
=====

First section
-------------

.. This is comment

<section>
  <h1>Title</h1>
</section>
<section>
  <section>
    <h2>First section</h2>
  </section>
</section>

reSTのコメントは、デフォルトの設定では出力されません。

セクションの挙動をカスタマイズする

概要

sphinx-revealjs はセクション単位での挙動設定をするためのディレクティブを用意しています。

• revealjs-section

• revealjs-break

ここからは、いくつかの例を紹介します。

背景色の変更

.. revealjs-section::
   :data-background-color: #009900

背景色の変更

.. revealjs-section::
   :data-background-gradient: linear-gradient(to bottom, #283b95, #17b2c3)

背景に画像の差し込み

.. revealjs-section::
   :data-background-image: _static/icon-attakei.jpg
   :data-background-size: contain

セクション間の切り替えの動き(1)

.. revealjs-section::
   :data-transition: none

セクション間の切り替えの動き(2)

.. revealjs-section::
   :data-transition: concave

タイトルを持たないセクション

First

Keep title without duplicated written
-------------------------------------

First

.. revealjs-break::
   :notitle:

Second

Second

Keep title without duplicated written
-------------------------------------

First

.. revealjs-break::
   :notitle:

Second

インタラクティブな内容

概要

sphinx-revealjs はインタラクティブなプレゼンテーションを提供するためのディレクティブも用意しています。

• revealjs-section

• revealjs-break

• revealjs-fragments

ここからは、いくつかの例を紹介します。

コードブロックのアニメ表示

revealjs-section や revealjs-break を用いてアニメーションの設定が可能です。

echo 'First part of my command'

コードブロックのアニメ表示

revealjs-section や revealjs-break を用いてアニメーションの設定が可能です。

echo 'First part of my command'
echo 'Second part of my command'

Fragments

表示対象のグループに対して、Fragments表示を組み込めます。

.. revealjs-fragments::

   * First
   * Second
   * Third

• First

• Second

• Third

Fragments

You can customize behavior of fragments.

.. revealjs-fragments::
   :custom-effect: blur

   * First
   * Second
   * Third

// For custom effect of fragments
.fragment.blur {
  filter: blur(5px);
}
.fragment.blur.visible {
  filter: none;
}

Fragments

You can customize behavior of fragments.

.. revealjs-fragments::
   :custom-effect: blur

   * First
   * Second
   * Third

• First

• Second

• Third

Fragments

container ディレクティブを使うことで、Fragmentsを重ねて表示させることが出来ます。

.. container:: r-stack

   .. revealjs-fragments::

      .. image:: https://placekitten.com/450/300

      .. image:: https://placekitten.com/300/450

      .. image:: https://placekitten.com/400/400

Fragments

container ディレクティブを使うことで、Fragmentsを重ねて表示させることが出来ます。

Reveal.jsプラグインの利用

概要

sphinx-revealjs は conf.py 内で revealjs_script_plugins を記述することで、Reveal.jsのプラグインを利用することが出来ます。

revealjs_script_plugins = [
    {
        "name": "RevealMath",
        "src": "revealjs/plugin/math/math.js",
    },
]

コードのハイライト

revealjs_script_plugins = [
    {
        "name": "RevealHighlight",
        "src": "revealjs/plugin/highlight/highlight.js",
    },
]

RevealHighlight プラグインを利用することで、コードブロックのシンタックスハイライトが可能です。

コードのハイライト

.. code-block:: python

   print("hello world")

code-block と literalinclude はそのまま使えます。

コードのハイライト

.. revealjs-code-block:: rst
   :data-line-numbers: 1|2

   print("hello world")

revealjs-code-block であれば、行単位のハイライトなども機能します。

コードのハイライト

revealjs_script_conf = {
    "controls": True,
    "progress": True,
    "hash": True,
    "center": True,
    "transition": "slide",
}
revealjs_script_plugins = [
    {
        "name": "RevealNotes",
        "src": "revealjs/plugin/notes/notes.js",
    },
    {
        "name": "RevealHighlight",

revealjs-literalinclude も同様に使えます。

コードのハイライト

.. revealjs-code-block:: python
   :data-ln-start-from: 47

revealjs_script_plugins = [
    {
        "name": "RevealHighlight",
        "src": "revealjs/plugin/highlight/highlight.js",
    },
]

data-ln-start-from を使うことで、行番号の開始値を調整できます。

コードのハイライト

    "progress": True,
    "hash": True,
    "center": True,
    "transition": "slide",
}
revealjs_script_plugins = [
    {
        "name": "RevealNotes",
        "src": "revealjs/plugin/notes/notes.js",
    },
    {
        "name": "RevealHighlight",
        "src": "revealjs/plugin/highlight/highlight.js",
    },

revealjs-literalinclude も同様に使えます。

スピーカーノート

revealjs_script_plugins = [
    {
        "name": "RevealNotes",
        "src": "revealjs/plugin/notes/notes.js",
    },
]

RevealNotes プラグインを利用することで、スピーカーノートを使えます。 キーボードの S を押して試してください。

スピーカーノート

.. revealjs-notes::

   In this section, showing message from notes.