SphinxにLilyPondを組み込む

Sphinxは、Pythonで書かれたドキュメント生成ツールです。reStructuredTextを用いて、高品位の出力を得ることができます。Pythonによる拡張が容易です。
LilyPondは、C++およびSchemeで書かれた楽譜生成ツールです。独自の言語を用いて、高品位の出力を得ることができます。Schemeによる拡張が容易です。

似たもの同士ですね。こいつらを組み合わせて、高品位の楽譜付きドキュメントを作れるようにしてみたいと思います。

どうなるの？

シンタックスハイライトに対応していて、出力画像はSVGになっているので綺麗です。公式マニュアルの出力よりモダンな感じがしますね。
もっと見たい方はLilyPond四週間（未完成）へ。また、具体的にどうやって組み込んでいるかはソースコードのextensions/とsource/conf.pyを見てください。

Directive

.. lily::
  :caption: タイ
  :name: tie-example

  \relative c' {
    c2~ c8 g'4 f8~ 8. e16~ 8 d8 c2
  }

こんな感じでソースコードを入力すると、画像のようにコードと出力が並んで出力されるようにするのが目標です。そのためにlilyディレクティブを作ります。

Original by Wei-Wei Guo

偉大なる先駆者です。
機能としては、ソースコードからpng画像を出力するという、最低限のものです。

Improved by Fabrice Salvaire

Python3用にクリーンアップし、独立したものです。LilyPondがSVGのクロップに対応し次第¹SVG出力にも対応する予定だそうです。

改造しました

PyPIには登録していないので（READMEの手順を踏むとフォーク元のものがインストールされます）、自前でcloneしてパスを通して使ってください。

SVG画像を出力するようにしました。上に書いたように、まだ公式でSVGのクロップに対応していないため、一旦PDFでクロップされた出力を得て、それをSVGに変換するという手順を取っています。そのため、外部ツールpdf2svgが必要です。

画像のように、ソースコードと出力画像が併置されるようにしました（オプションで変更可能）。

また、大量のオプションが追加されています。

• nowrap: 実質、互換性のために残されているようなものです。本来は、入力を\new Staff << >>で囲ったりせずに生のデータを用いて出力するようになるオプションです。
• linenos: 行番号を表示します。
• lineno-start: 行番号を表示する時、何行目から開始するかを指定します。
• emphasize-lines: ハイライトする行番号を指定します。
• caption: コードの上に表示するタイトルを表示します。
• name: クロスリファレンスに用いる名前を指定します。
• without-code: ソースコードを表示しません。
• without-image: 出力画像を表示しません。

とは言え、LilyPond四週間のために突貫工事したものですので、LaTeX対応が無くなっていたり、インライン表記（ロール）対応が無くなってたり、色々と削減されている機能も多いです。このあたりは要改善。

Pygments Lexer

Sphinxは、ソースコードのシンタックスハイライトにPygmentsを使っています。残念ながら、公式のLexerリストにはLilyPondが無いため、自分でLexerを用意する必要があります。

Original by Jeffery Shivers

先駆者がいるというのは、本当にありがたいことです。

改造しました

オリジナルをそのまま使うだけではハイライトが不十分だったため、フォークしていくらか修正しました。まだまだ対応していない記法があるはずなので、要改善。

なお、SphinxにLexerを認識させるには、こんな感じにする必要があります。conf.pyに書くなり、拡張を書くなりすると良いでしょう。

from lilypondlexer import lilypond

def setup(app):
    app.add_lexer("lilypond", lilypond.LilyPondLexer())

---

1. LilyPondのmasterブランチに-dcropオプションが実装されました。2.20で使用可能になるかと思いきや、stable/2.20ブランチには組み込まれていません。Changesドキュメントには書いてあるのですが…。メーリングリストにこの件を投げたことがあるのですが、安定版候補のブランチに新しく機能を組み込むことには慎重なようです。果たしてどうなるか。 (12/25追記)stable/2.20ブランチに取り込まれたようです。次のリリースで使用可能になりそうな予感。 ↩