LaTeXマークアップとの違い

マークアップ言語は異なりますが，古いLaTeXドキュメントのほとんどのコンセプトとマークアップタイプは維持されています - reSTディレクティブとしての環境，reSTロールとしてのインラインコマンドなど．

ただし，マークアップ言語の違い，Sphinxの改良により，これらの動作方法にはいくつかの違いがあります．このセクションでは，これらの違いについて説明します．古い形式に慣れた方が陥る可能性があるものの概要を簡単に説明するためです．

インラインマークアップ

インラインマークアップに次の変更が加えられました．

• 相互参照ロール

  以下のセマンティック・ロールの大部分は，以前はインライン・コマンドとして存在していましたが，内容をコードとしてフォーマットすること以外は何もしませんでした．次に，既知のターゲット(一部の名前も短縮されている)を相互参照します．

  mod (以前の refmodule または module)

  func (以前の function)

  data (新しい)

  const

  class

  meth (以前の method)

  attr (以前の member)

  exc (以前の exception)

  cdata

  cfunc (以前の cfunction)

  cmacro (以前の csimplemacro)

  ctype

  また， func と meth の処理も異なります．以前は呼び出し可能な名前( \func{str()} のような)に括弧が追加されていましたが，現在はビルドシステムによって追加されています．ソースに括弧を追加すると二重括弧になります．これは， :func:`str(object)` が期待通りに動作しないことも意味します．代わりに ``str(object)`` を使用してください．

• 命令として実装されたインラインコマンド

  これらはLaTeXのインラインコマンドでしたが，現在はreSTのディレクティブです．

  廃止

  バージョン追加

  バージョン変更

  これらは次のように使用されます．

  .. deprecated:: 2.5
     Reason of deprecation.
  

  また，* versionadded および versionchanged *のテキストにピリオドは追加されません．

  注意

  警告

  これらは次のように使用されます．

  .. note::
  
     Content of note.
  

• その他の変更されたコマンド

  The samp command previously formatted code and added quotation marks around it. The samp role, however, features a new highlighting system just like file does:

  ``：samp： open（{filename}，{mode}） ``の結果は：samp： `open（{filename}，{mode}）`になります

• ドロップされたコマンド

  これらはLaTeXのコマンドでしたが，ロールとしては使用できません．

  bfcode

  character (``'c'`` を使用してください)

  citetitle ( `Title <URL>`_ を使用してください)

  code (``code`` を使用してください)

  email (アドレスを本文に書くだけでいいです)

  filenq

  filevar (file の {...} 強調表示機能を使用します．)

  programopt, longprogramopt (option を使用してください)

  ulink ( `Title <URL>`_ を使用してください)

  url (本文にURLを書くだけです)

  var ( *var* を使用してください)

  infinity, plusminus (Unicode文字を使用します)

  shortversion ， version ( |version| および |release| 置換を使用します)

  emph，*strong*(reST markupを使用します)

• バックスラッシュエスケープ

  reSTでは，通常のテキストとロールの内容でバックスラッシュをエスケープする必要があります．ただし，コードリテラルおよびリテラルブロックでは，エスケープしないでください．例 :file:`C:\\Temp\\my.tmp` vs. ``open("C:\Temp\my.tmp")`` ．

情報単位

Information units (...desc 環境)はreSTディレクティブとなります．情報単位に対する次の変更に注意してください．

• 新しい名前

  "desc" は全ての名前から削除されました．さらに，これらのディレクティブには新しい名前があります．

  c:function (以前の cfuncdesc)

  cmacro (以前は csimplemacrodesc )

  exception (以前の excdesc)

  function (以前の funcdesc)

  attribute (以前は memberdesc )

  classdesc* と excclassdesc 環境が削除され， class と exception ディレクティブは，コンストラクタ引数の有無に関わらず，記述されたクラスをサポートします．

• 複数のオブジェクト

  ...line コマンドに相当するものは次のとおりです．

  .. function:: do_foo(bar)
                do_bar(baz)
  
     Description of the functions.
  

  IOWは，同じインデントレベルで1行に1つの記号を付けるだけです．

• 引数

  optional コマンドはありません．出力に表示されるような関数記号を与えてください．

  .. function:: open(filename[, mode[, buffering]])
  
     Description.
  

  注意：記号のmarkupはサポートされていません．

• インデックス作成

  ...descni 環境が削除されました．情報単位をインデックスエントリ生成に適さないものとしてマークするには，次のように noindex オプションを使用します．

  .. function:: foo_*
     :noindex:
  
     Description.
  

• 新しい情報単位

  新しい一般情報の単位が追加されました．これは "describe" と呼ばれ，他の単位でカバーされていない内容を文書化するために使用できます．

  .. describe:: a == b
  
     The equals operator.
  

  その他は次のとおりです．

  .. cmdoption:: -O
  
     Describes a command-line option.
  
  .. envvar:: PYTHONINSPECT
  
     Describes an environment variable.
  

構造

LaTeX文書はいくつかのトップレベルのマニュアルに分割されています．現在では，すべてのファイルが同じドキュメントツリーの一部になっています．これはソースの toctree ディレクティブによって示されています(ただし，個々の出力形式では，それらを再びパーツに分割することもできます．)．すべての toctree ディレクティブは，他のファイルを現在のファイルのサブ文書として埋め込みます(この構造は必ずしもファイルシステムのレイアウトに反映されるとは限らない)．トップレベルファイルは contents.rst です．

ただし，古いディレクトリ構造のほとんどは保持されており，ディレクトリ名は次のように変更されています．

• api -> c-api

• dist -> distutils ，TeXファイル1つを分割します

• doc -> documenting

• ext -> extending

• inst -> installing

• lib -> library

• mac -> library に統合され， mac/using.tex が using/mac.rst に移動しました

• ref -> reference

• tut -> tutorial，TeXファイル1つを分割します