Sphinxとsphinx-revealjsの勉強

概要

Sphinxを使ったドキュメント作成を勉強するためにまとめたもの。

概念の理解

• Sphinx（スフィンクス）
  python製のプレゼンテーションビルダー（知的で美しいドキュメントを簡単に作れるようにするツール）。
  Georg Brandlによって開発され、BSDライセンスのもとで公開されている。
  SphinxはreStructuredTextという記法を使用して、reSTファイル（拡張子.rst）を作成する。
• 特徴
  • 出力形式
    • HTML (WIndowsのHTMLヘルプを含む)
    • LaTeX(印刷可能なPDFバージョン)
    • ePub（Electronic PUBlicationの略称、open formatの電子書籍file format規格）
    • Texinfo（GNUのドキュメンテーションシステム）
    • man
    • プレーンテキスト
  • パッケージ
    PyPI（Python Package Index）に公開されている。
• sphinx-revealjs
  Sphinx拡張の1つ、Sphinxで読み取った入力ソースを、Reveal.jsのプレゼンテーション形式のHTMLとして出力するもの。
  • 特徴
    SphinxのビルトインHTML出力では表現できないReveal.jsの構造に合わせた出力をするようになっている。
• Reveal.js
  Hakim El Hattabによって開発されている、HTMLでのプレゼンテーションを作成するためのフレームワーク。
  • 特徴
    左右移動でメインセッションの進行、上下移動でサブセッションの進行という表現。
    • 例
      https://revealjs.com/
  • github.com
    https://github.com/hakimel/reveal.js

動かしてみる

まずは簡単なものから

• 仮想環境を準備

$ mkdir -p ~/dev/sphinx
$ cd !$
$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $

• Sphinxドキュメンテーションを新規作成

$ pip install "Sphinx==3.4.3" "sphinx-revealjs==1.0.1"
（省略）
Successfully installed Jinja2-3.0.1 MarkupSafe-2.0.1 Pygments-2.10.0 Sphinx-3.4.3 alabaster-0.7.12 babel-2.9.1 certifi-2021.5.30 charset-normalizer-2.0.6 docutils-0.17.1 idna-3.2 imagesize-1.2.0 packaging-21.0 pyparsing-2.4.7 pytz-2021.1 requests-2.26.0 snowballstemmer-2.1.0 sphinx-revealjs-1.0.1 sphinxcontrib-applehelp-1.0.2 sphinxcontrib-devhelp-1.0.2 sphinxcontrib-htmlhelp-2.0.0 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-1.0.3 sphinxcontrib-serializinghtml-1.1.5 urllib3-1.26.7

• クイックスタートユーティリティsphinx-quickstartを実行

$ sphinx-quickstart
Sphinx 3.4.3 クイックスタートユーティリティへようこそ。

以下の設定値を入力してください（Enter キーのみ押した場合、
かっこで囲まれた値をデフォルト値として受け入れます）。

選択されたルートパス: .

Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。
ルートパス内にある "_build" ディレクトリを使うか、
ルートパス内に "source" と "build" ディレクトリを分ける方法です。
> ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: y

プロジェクト名は、ビルドされたドキュメントのいくつかの場所にあります。
> プロジェクト名: My presentation
> 著者名（複数可）: Liu Ganxiang
> プロジェクトのリリース []:

ドキュメントを英語以外の言語で書く場合は、
 言語コードで言語を選択できます。Sphinx は生成したテキストをその言語に翻訳します。

サポートされているコードのリストについては、
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language を参照してください。
> プロジェクトの言語 [en]: ja

ファイル /Users/■■■/dev/sphinx/source/conf.py を作成しています。
ファイル /Users/■■■/dev/sphinx/source/index.rst を作成しています。
ファイル /Users/■■■/dev/sphinx/Makefile を作成しています。
ファイル /Users/■■■dev/sphinx/make.bat を作成しています。

終了：初期ディレクトリ構造が作成されました。

マスターファイル /Users/■■■/dev/sphinx/source/index.rst を作成して
他のドキュメントソースファイルを作成します。次のように Makefile を使ってドキュメントを作成します。
 make builder
"builder" はサポートされているビルダーの 1 つです。 例: html, latex, または linkcheck。

ディレクトリ構造を確認してみると

$ ls -R
.:
Makefile  build  make.bat  source

./build:

./source:
_static  _templates  conf.py  index.rst

./source/_static:

./source/_templates:

になっている。

• プレゼン資料の中身を書く
  生成されたファイルの中にsource/index.rstがあり、これはドキュメントとして扱うソースになる。バックアップしてから適当な内容を入れてみる。

$ cp -p source/index.rst{,.org}
$ vim source/index.rst
========================================
Sphinxでのプレゼンテーションを初体験する
========================================

準備
====

準備内容1
------------------------

適当に何かを書く

準備内容2
------------------------

適当に何かを書く。

内容中身
========

内容を書く

• sphinx-revealjsを組み込み、ビルドする
  目的：拡張機能の設定を追加することにより、プレゼンできるようにする。
  まずは設定する：

$ vim source/conf.py
# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
   # 使用する拡張としてsphinx-revealjsを新規追加
   'sphinx_revealjs',
]

最低限ここだけを編集するだけで、プレゼン用のビルドができるようになる。

次はビルドする：

$ make revealjs
Sphinx v3.4.3 を実行中
翻訳カタログをロードしています [ja]... 完了
出力先ディレクトリを作成しています... 完了
ビルド中 [mo]: 更新された 0 件のpoファイル
ビルド中 [revealjs]: 更新された 1 件のソースファイル
環境データを更新中[新しい設定] 1 件追加, 0 件更新, 0 件削除
ソースを読み込み中...[100%] index
更新されたファイルを探しています... 見つかりませんでした
環境データを保存中... 完了
整合性をチェック中... 完了
preparing documents... 完了
出力中...[100%] index
索引を生成中... genindex 完了
追加のページを出力中... search 完了
copying static files... 完了
extraファイルをコピー中... 完了
Japanese (code: ja) の検索インデックスを出力... 完了
オブジェクト インベントリを出力... 完了
ビルド 成功.

HTMLページはbuild/revealjsにあります。

これで、静的なHTMLファイルがbuild/revealjs配下に作成され、index.htmlをブラウザでみれる。

• 改良1：テーマを変えてみる
  sphinx-revaljsでは何も設定がない場合、blackがデフォルトとして動作する。
  Reveal.jsでは組み込みでのカラーテーマがいくつか提供されているため、その中から変えてみる。
• Reveal.jsの組み込みテーマ一覧
  beige / black / blood / league / moon / night / serif / simple / sky / solarized / white

moonに変えてみる

$ vim source/conf.py
revealjs_style_theme = 'moon'

設定しただけではすぐ反映されないため、再度ビルドする。

$ make revealjs

再度ブラウザでみると、背景が変わった。

• 改良2：CSSで見た目を変える
  Reveal.jsのテーマでは、各セッションの見出しの英字テキストが全て大文字になるようで、CSSを作ってこの設定を解除する。
  Sphinxでドキュメントをまたいで使う静的ファイルは_staticフォルダで管理することが多いため、その配下に以下のCSSファイルを配置する。

$ vim source/_static/slides.css
.reveal h1, .reveal h2, .reveal h3, .reveal h4, .reveal h5 {
  text-transform: none;
}

• ビルド時にCSSを組み込むようにする
  CSSファイルを用意しただけでは取り込んでくれないので、source/conf.pyを編集して「プレゼンテーションHTML生成時にCSSを使用する」設定を加える。

$ vim source/conf.py
revealjs_static_path = html_static_path
revealjs_css_files = [
    "slides.css",
]

再びmake revealjsして、するとブラウザからみたら

SPHINXがSphinxに変わった。

SphinxでHTML出力の場合

上の例だと、sphinx-revealjs拡張機能でHTML（プレゼン）した事例だが、本来sphinxからHTMLを出力した場合の結果も確認しておく。

$ make html

でビルドし、build/html配下に出力され、ブラウザからindex.htmlを確認すると、以下のようになる

カラーテーマの設定がない普通のHTMLページになる。

次は→Reveal.jsプラグインやSphinx拡張を活用して、質の向上を目指す を勉強する。

参考資料（THX!）

• Sphinxでもプレゼンテーション（基本これを参考に）
• Sphinxの日本ユーザ会
• プレゼン？それもSphinxで出来るよ
• 初心者がどのようにSphinxを使ってきたかという記録（ちょっと古い）
• sphinx-revealjs
• revealjs DEMO