sphinx-revealjsの紹介

Based version:: 3.0.5
Demo updated:: 2024-10-18 JST

基本的な説明

これはなにか

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

主な機能

reStructuredTextの文法構造からReveal.jsのセクション構造を生成
セクションのカスタマイズ機能
Reveal.js向けのプラグイン組み込み
Sphinx拡張の利用
組み込みのテーマ切り替え

基本的な使い方

インストール

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

pip install sphinx-revealjs

セットアップ

Edit conf.py to use this extension.

extensions = [
    "sphinx_revealjs",
]

You can customize behavior. Please see documentation.

ソースを作成

標準的な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>
    <section>
        <h1>Title</h1>
    </section>
</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

oembed is custom directive from oEmbedPy.

出力:

Now, sphinx-revealjs v1.5.1 is released (fixed template and modify project links).
Thank you for usings, feedbacks, suggestions and collaborations!https://t.co/dr0rFNdg9z
— kAZUYA tAKEI (@attakei) April 21, 2022

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-vertical )

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

背景色の変更

.. 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

Customse all slide of one vertical items

If you want to change behaivor of all slides on vertical slides (level 2 section), set revealjs-vertical.

.. Changing background-color of vertical slides (items scrolled bottom)

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

インタラクティブな内容

概要

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

revealjs-section
revealjs-break
revealjs-fragments

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

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

Enable animations for each revealjs-section and revealjs-break:

echo 'First part of my command'

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

Enable animations for each revealjs-section and 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://picsum.photos/450/300

      .. image:: https://picsum.photos/300/450

      .. image:: https://picsum.photos/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_static_path = ["_static"]
revealjs_style_theme = "custom.css"
revealjs_script_conf = {
    "controls": True,
    "progress": True,
    "hash": True,
    "center": True,
    "transition": "slide",
    "customcontrols": {
        "controls": [
            {
                "icon": "EN",
                "action": "location.href = '/en/';",
            },

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 を使うことで、行番号の開始値を調整できます。

コードのハイライト

revealjs_script_conf = {
    "controls": True,
    "progress": True,
    "hash": True,
    "center": True,
    "transition": "slide",
    "customcontrols": {
        "controls": [
            {
                "icon": "EN",
                "action": "location.href = '/en/';",
            },
            {
                "icon": "JA",

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

スピーカーノート

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

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

スピーカーノート

.. revealjs-notes::

   In this section, showing message from notes.

reStructuredTextでのプレゼンテーションをぜひ体験してみてください。

Please star!

Star