sphinx-revealjs

（自分を含む）日本で sphinx-revealjs を利用している人向けの、README補完+αのテキスト。

概要

sphinx-revealjs は、reStrucuredTextのソースをReveal.js形式のプレゼンテーションに変換するためのSphinx拡張。

リリース周りの話

自分の中である程度決めてはいるものの、英文として変化するのがちょっと手間なリリース戦略周りについて書き起こす。

セマンティックバージョニングの採用

基本思想として セマンティックバージョニング2.0.0 を採用している。 そのため、基本的には以下の通りの更新を実施している。

• メジャーバージョンの更新条件

  • ライブラリとして広報互換性を失う更新を行う

• マイナーバージョンの更新条件

  • 広報互換性を維持しつつ、新しい機能を追加する

  • 後述の依存処理ルールに基づいて、非推奨な要件が発生する

• パッチバージョンの更新条件

  • ライブラリとしての機能に発生していた不備を改修する

  • Reveal.jsのマイナーバージョン以下の更新を取り込む

リリースのクールタイム

sphinx-revealjs の開発は、「自分がプレゼンテーションであると嬉しい」機能を実装するのが基本スタイルとなっている。 そのため、マイナーバージョン以上の更新に対するクールタイムを用意して、意識的なドッグフーディングを行うようにしている。

目安としては、以下のとおり。

• マイナーバージョン更新後は 1ヶ月 を標準クールタイムとして、この期間はパッチバージョン更新のみを行う

• メジャーバージョン更新後は 最低3ヶ月 を標準クールタイムとして、この期間はマイナーバージョン更新までしか行わない

依存先との付き合い方

この sphinx-revealjs は Reveal.js を用いた Python 製の Sphinx の拡張ライブラリという立ち位置になっている。 つまり、これらの3プロダクトに直接依存している。

いずれもアクティブなプロダクトであるため、それなりのペースで更新が行われていくのだが、 なるべくならバージョンの変化に追従できる体制を取ることが望ましい。

そこで、ある程度の指標として以下のような方針を定めている。

対Reveal.js

sphinx-revealjs はSphinxの拡張ビルダーとしてReveal.js向けのHTMLを生成する仕組みとなっている。 Reveal.jsはフロントエンド系のライブラリであり、CDN提供されていることも併せて、 比較的最新バージョンのものがすぐに使われる傾向が強い。

そのため、「可能な限り追従する」体制を取るために、GitHub Actionsで監視を行いつつ、以下の方針を取るようにしている。

• マイナー以下のバージョン更新が発生した場合は、速やかに取り込みを行って sphinx-revealjs のパッチバージョン更新として対応する

• メジャーなバージョン更新が発生したっ場合は、以下のスタイルを基準に対応する

  • X.0 が登場した時点で、マイナーバージョン更新として「新旧両バージョンの取り込み」を行う。この時点では「新バージョンの利用は実験的」扱いとする

  • その後に X.1 が出るまでは、上記更新以降から「バージョン選択制・どちらのバージョンでもプレゼンテーション表現に変化がない」体制を維持する

  • X.1 が出たあたりで、まずは「旧バージョン利用を非推奨」とするマイナーバージョン更新を行う

  • 次のメジャーバージョン更新のタイミングで、旧バージョンの取り込みをやめる

対Sphinx

課題

ぼんやりと考えているけど、文字化化がまだ

対Python

課題

ぼんやりと考えているけど、文字化化がまだ