コードサンプルの表示

Pythonのソースコードや、インタラクティブモードのセッションを表現するのには、標準のreSTのリテラルブロックを使用します。リテラルブロックは前の段落の末尾を :: にして、インデントにすることで開始されます。

インタラクティブセッションの表現には、プロンプトと、Pythonコードが表示する出力も含める必要があります。インタラクティブセッション用の特別なマークアップはありません。最後の行の後、もしくは出力を書いているところには、”未使用の”プロンプトは置いてはいけません。下記の例は しないほうがいいもの の例です。:

>>> 1 + 1
2
>>>

シンタックスハイライトは Pygments によって行われ、無駄のない方法で制御されます:

  • ソースファイルごとに”ハイライトする言語”があります。一番ハイライトされる言語として多いのはPythonのコード片なので、デフォルトでは 'python' として処理するようになっています。ドキュメント全体のデフォルトの設定は highlight_language で設定できます。

  • Pythonハイライトモードではインタラクティブモードも自動で識別され、適切にハイライトされます。通常のPythonコードはパース可能であればきちんとハイライトされます。しかし、シェルコマンドや他のコードブロックの部分的なコード片はPythonとして処理できないこともあります。

  • ハイライト言語は highlight ディレクティブを以下のようにして変更できます:

    .. highlight:: language

    サンプル:

    .. highlight:: c
    

    ここで設定された言語は、次に highlight ディレクティブが実行されるまで有効です。

  • 様々な言語のコード片がドキュメント中に登場する場合には、 code-block ディレクティブを使用すると、その場でハイライトしたい言語を指定できます:

    .. code-block:: language

    以下のように使用します:

    .. code-block:: ruby
    
       Some Ruby code.
    

    このディレクティブのエイリアスの sourcecode も同じように動作します。

  • ハイライトする言語として適切な値は以下の通りです:

  • 選択された言語によるハイライトがうまくいかなかった場合(例えば、Pygmentsが”Error”トークンを出す等)には、そのブロックはハイライトされなくなります。

行番号

Pygments はコードブロックの行番号を生成することができます。 自動的にハイライトされたブロック(:: から始まるブロック)の行番号は必ず highlight ディレクティブの中で linenothreshold オプションを有効にしてください:

.. highlight:: python
   :linenothreshold: 5

この設定では5行以上あるコードブロックのすべてに対して、行番号が生成されるようになります。

code-block ブロックを使用している場合には、 linenos フラグオプションを使用すると、個別のブロックの行番号表示を有効にできます:

.. code-block:: ruby
   :linenos:

   Some more Ruby code.

The first line number can be selected with the lineno-start option. If present, linenos is automatically activated as well.

10
Some more Ruby code, with line numbering starting at 10.

また、 emphasize-lines オプションは強調表示する行をPygmentsに指示します。

.. code-block:: python
   :emphasize-lines: 3,5

   def some_function():
       interesting = False
       print 'This line is highlighted.'
       print 'This one is not...'
       print '...but this one is.'

バージョン 1.1 で変更: emphasize-lines を追加しました。

バージョン 1.3 で変更: lineno-start を追加しました。

インクルード

.. literalinclude:: filename

プレーンテキスト形式で外部ファイルとして保存指定あるサンプルのテキストを引用して表示することもできます。長いソースコードを正確にそのまま表示したい場合に便利です。ファイルをインクルードするには、 literalinclude ディレクティブを使用します。 [1] 例えば、 example.py というPythonソースコードをインクルードするには以下のようにします:

.. literalinclude:: example.py

ソースコードのファイルは通常、現在のパスからの相対パスで指定します。 / から開始されているときはトップのソースディレクトリからのパス指定をできます。

tab-width オプションを指定すると、入力ファイル中のタブを希望の幅に展開できます。

code-block のように、このディレクティブも linenos フラグオプションを利用して行番号表示を有効にできます。また、 lineno-start オプションで最初の行番号指定し、 emphasize-lines で指定した行を強調できます。加えて、 language オプションを使うと、ファイルの標準の言語と違う言語を選択できます。オプションのサンプルを示します:

.. literalinclude:: example.rb
   :language: ruby
   :emphasize-lines: 12,15-18
   :linenos:

読み込むファイルは source_encoding で設定されているエンコードで保存されているものとして処理されます。もし違うエンコーディングのファイルを読み込む場合には encoding オプションで設定できます:

.. literalinclude:: example.py
   :encoding: latin-1

このディレクティブは、ファイル全体ではなく、一部分だけを読み込むこともサポートしています。もしPythonモジュールの場合には、 pyobject オプションを使用してクラス、関数、メソッドの単位でインクルードすることもできます:

.. literalinclude:: example.py
   :pyobject: Timer.start

上記のサンプルを書くと、指定されたファイルに含まれる、 Timer クラスの start() メソッドに属するコード行だけがドキュメントに挿入されます。

これとは別に、 lines オプションを使って行番号を正確に指定することでも部分的なインクルードを行えます:

.. literalinclude:: example.py
   :lines: 1,3,5-10,20-

このサンプルはでは、指定されたファイルの 1行目, 3行目, 5〜10行目, そして20行目から最終行までのコードがインクルードされます。

どのパートをインクルードするか、というのを制御する別の方法としては、 start-after, end-before オプションの両方、もしくはどちらか一方を使うものがあります。 もしスタートのオプションとして start-after にオプションとして文字列が指定されると、その文字列を含む行から始まるコードがインクルードされます。 end-before にオプションとして文字列が指定されると、指定された文字列が含まれる行の前の部分がインクルードされます。

ファイルの一部を表示するように指定した場合、ファイルの行番号をそのまま表示するように指定することもできます。その場合は、 lineno-match オプションを設定して下さい。

prepend, append オプションを使用すると、読み込まれた行の前後にコード行を追加できます。例えば、 <?php/?> マーカーを含まないPHPコードをハイライトする際などに役立ちます。

もしあなたがコードの差分を表示したいなら、diff オプションを与えて古いファイルを記述できます:

.. literalinclude:: example.py
   :diff: example.py.orig

このオプションはexample.pyとexample.py.origの差分をユニファイドdiffフォーマットで表示します。

バージョン 0.4.3 で追加: encoding オプションを追加しました。

バージョン 0.6 で追加: pyobject, lines, start-after, end-before オプションと、絶対パスファイル名のサポートを追加しました。

バージョン 1.0 で追加: prepend, append, tab-width を追加しました。

バージョン 1.3 で追加: diff オプション、lineno-match オプション。

captionとnameオプション

バージョン 1.3 で追加.

caption オプションはコードブロックの前に表示する文字列を指定します。 name オプションは ref で参照できるターゲット名です。例:

.. code-block:: python
   :caption: this.py
   :name: this-py

   print 'Explicit is better than implicit.'

literalincludecaptionname オプションをサポートします。 caption の追加機能として、値を空で指定した場合、ディレクティブの引数に指定したファイル名がキャプションとして使用されます。

Dedent

バージョン 1.3 で追加.

dedent オプションによってコードブロック内にあるインデントを取り除くことができます。例:

.. literalinclude:: example.rb
   :language: ruby
   :dedent: 4
   :lines: 10-15

code-blockdedent オプションをサポートします。

脚注

[1]

標準の .. include ディレクティブは、ファイルがないときにはエラーが発生しますが、こちらの方は警告を出力します。