コードサンプルの表示

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

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

>>> 1 + 1
2
>>>

シンタックスハイライトは、もしインストールされていれば Pygments を使ってスマートに行われます。

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

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

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

  .. highlight:: c
  

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

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

  .. code-block:: ruby
  
     Rubyのプログラム
  

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

• ハイライトする言語として適切な値は以下の通りです:
  • none (ハイライトしない)
  • python ( highlight_language が設定されていない時のデフォルト)
  • guess (Pygmentsに推測させます。推測しやすい言語でないとうまく動作しません)
  • rest
  • c
  • ... など、Pygmentsがサポートしているすべての言語

• 選択された言語によるハイライトがうまくいかなかった場合には、そのブロックはハイライトされなくなります。

行番号

もしインストールされていれば、Pygmentsはコードブロックに対して行番号を発生させることができます。自動ハイライトブロック( :: で開始されるもの)を使用している場合には、 highlight ディレクティブの中で、 linenothreshold オプションを使って機能を有効にする必要があります:

.. highlight:: python
   :linenothreshold: 5

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

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

.. code-block:: ruby
   :linenos:

   Rubyのコード

インクルード

.. literalinclude:: ファイル名

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

example.py, を使用する:

.. literalinclude:: example.py

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

このディレクティブでも、 linenos フラッグオプションを利用して、行番号表示を有効にすることができます。また、 language オプションを使うと、ファイルの標準の言語と違う言語を選択することができます。オプションのサンプルを示します:

.. literalinclude:: example.rb
   :language: ruby
   :linenos:

読み込むファイルは source_incodeing で設定されているエンコードで保存されているものとして処理されます。もし違うエンコーディングのファイルを読み込む場合には 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 にオプションとして文字列が指定されると、指定された文字列が含まれる行の前の部分がインクルードされます。

バージョン 0.4.3 で追加: encoding オプション

バージョン 0.6 で追加: pyobject, lines, start-after, end-before オプションと、プロジェクトのルートからの絶対パス指定

脚注

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