ReStructiredText Primer(テキスト入門を再構築)

ReStrutiredTextはSphinxが使用するデフォルトプレーンテキストマークアップ言語である.この部分は，著者に十分な情報を提供して効率的に文書を作成することを目的としたreStructiredText(REST)の概念と文法を簡単に紹介している.RESTは簡単で目立たないマークアップ言語として設計されているため，あまり時間がかからない.

参考

権威者. reStructuredText User Documentation それがそうです。本稿の“ref”リンクは，REST参照における各構造の記述を指す

段落

この話. (ref )は、REST文書の最も基本的なブロックです。段落は、1つまたは複数の空の行によって分離されたテキストブロックのみである。Pythonと同様に、インデントはRESTで重要であるため、同じパラグラフのすべての行が同じインデントレベルに達するように左に整列しなければなりません。

内連マーク.

標準RESTイントラネットマークは非常に簡単：使用

  • 星印です *text* (斜体)を強調するために

  • 2つの星番号： **text** (太字を)強調し，

  • 逆引用符： ``text コード例の`.

連続テキスト中にスター記号または逆引用符が出現し、行内ラベルセパレータと混同される可能性がある場合、逆スラッシュを使用して変換されなければならない。

このマークのいくつかの制限に注意してください。

  • 入れ子ではないかもしれません

  • 内容はスペースで始まることや終わりにすることはできません。 * text* 間違っています

  • それを非単語文字で周囲のテキストから分離しなければならない.逆スラッシュ変換スペースを使用してこの問題を解決します thisis\ *one*\ word それがそうです。

このような制限は未来のバージョンの文書でキャンセルされるかもしれない。

いくつかの連結マークをロールで置き換えたり、拡張したりすることもできる。参考にする 役柄 より多くの情報を得ることができます

リストと似たような見積もりのブロック

リストマーク (ref )は自然である：段落の先頭に星番号を加えて適切にインデントすればよい。番号リストも同様である # サイン：：

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

ネストリストは可能であるが、親リスト項との間を空の行で分離しなければならないことに留意されたい。

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

定義リスト (ref )を作成します。

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

この用語はテキストの一行以上を含んではいけないことに留意されたい。

引用段落. (ref )は、周囲の段落ではなく、それらをインデントすることによって作成されます。

回線ブロック. (ref )は、改行を保持する1つの方法である：

| These lines are
| broken exactly like in
| the source file.

さらに、いくつかの特別なブロックが選択可能である。

  • フィールドリスト (ref そして、 フィールドリスト ）

  • オプションリスト (ref ）

  • 引用符付き文字ブロック (ref ）

  • 文書テストブロック (ref ）

文字ブロック.

文字コードブロック (ref )を序言として特別な表記で終わる段落 :: それがそうです。文字ブロックはインデントしなければならない(すべてのパラグラフと同様に，周囲のパラグラフと空行で区切られている)：

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

の処理方法 :: マークは知能的です

  • それが個々の段落として出現する場合、その段落は文書から完全に削除される。

  • 前にスペースがあれば、そのタグを削除します。

  • もしその前に非スペースがある場合、そのマークは単一のコロンによって置き換えられるだろう。

このようにして、上の例の第1のセグメントの第2の文は、“次のセグメントはコードサンプルである”として提示される。

属性は，文書範囲内でこれらの文字ブロックのためのコードを強調表示することができる. highlight 指令はプロジェクトの範囲内で使用されています highlight_language オプションを構成します。♪the code-block 命令は、ブロック毎に強調表示を設定するために使用されてもよい。このような指示は後で議論されるだろう。

Doctestブロック

Doctestブロック (ref )は、文書文字列に切り取られて貼り付けられたインタラクティブなPythonセッションです。必要ありません literal blocks 文法です。Doctestブロックは空の行で終わらなければなりません not 未使用のプロンプトで終了する：

>>> 1 + 1
2

時計

For grid tables (ref), you have to "paint" the cell grid yourself. They look like this:

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

Simple tables (ref) are easier to write, but limited: they must contain more than one row, and the first column cells cannot contain multiple lines. They look like this:

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

他の2つの文法をサポートしています CSV表 そして 表をリストアップする それがそうです。彼らはある種の 明示的フラグブロック それがそうです。参考にする 時計 より多くの情報を得ることができます

セグメント化する.

節見出し. (ref )は、句読点を使用して部分タイトルに下線(または任意に下線を付して)を付けることによって作成され、少なくともテキスト：

=================
This is a heading
=================

一般に、構造はタイトルの順序によって決定されるので、いくつかの文字のタイトルレベルには割り当てられていない。しかし，この約束は Python's Style Guide for documenting これに従うことができます

  • # 部品に線を引く

  • * 線を引いて章に使う

  • = 横断面については

  • - ，分節に対して

  • ^ 小節については

  • " 段落については

もちろん、自分のタグ文字(REST文書を参照)を自由に使用し、より深い入れ子レベルを使用することができますが、ほとんどのターゲットフォーマット(HTML、LaTeX)がサポートする入れ子の深さは限られていることを覚えておいてください。

フィールドリスト

フィールドリスト (ref )は、以下のようにラベル付けされたフィールドシーケンスである。

:fieldname: Field content

Python文書に使われています

def my_function(my_arg, my_other_arg):
    """A function just for me.

    :param my_arg: The first of my arguments.
    :param my_other_arg: The second of my arguments.

    :returns: A message (just for me, of course).
    """

Sphinxは、標準的なdocutilsアクションを拡張し、文書の先頭で指定されたフィールドリストをブロックします。参考にする フィールドリスト より多くの情報を得ることができます

役柄

役割や“解釈テキストの役割”をカスタマイズする (ref )は、連結された明示的なフラグです。それは添付文書が特定の方法で解釈されなければならないということを意味する。Sphinxは、対応する部分に記載されているように、意味タグおよび識別子の交差参照を提供するために使用される。一般文法は :rolename:`content `.

Docutilsは以下の役割をサポートしています。

参考にする 役柄 Sphinx追加のための役割。

明示的標識

“明示的フラグ” (ref )は、脚注、特に強調表示された段落、注釈、および汎用命令のような特別な処理を必要とする多くの構造のためにRESTで使用される。

明示的フラグブロックは1行で始まる. .. 先頭にスペースを置き，同じインデントレベルの次の段で終了する.(明示的なフラグと通常の段落の間に空の行が必要です。これはちょっと複雑に聞こえるかもしれませんが、それを書くと十分直感的です)。

指令

指令 (ref )は、明示的にマークされた汎用ブロックである。役割とともにRESTの拡張機構の1つでもあり，Sphinxはそれを大量に使用している。

Docutilsは以下のコマンドをサポートしています。

  • Admonitions: attention, caution, danger, error, hint, important, note, tip, warning and the generic admonition. (Most themes style only "note" and "warning" specially.)

  • 画像：

    • image (別途参照) Images (下記参照)

    • figure (タイトルおよびオプションの例付き画像)

  • 他の主体要素：

    • contents (ローカルディレクトリ、すなわち現在のファイルのみのディレクトリ)

    • container (外部を生成するためのカスタムクラスを有する容器 <div> (HTML形式)

    • rubric (文書分割とは無関係な見出し)

    • topic, sidebar (special highlighted body elements)

    • parsed-literal (イントラネットタグをサポートする文字ブロック)

    • epigraph (オプションのホーム行を有するブロックオファー)

    • highlights, pull-quote (block quotes with their own class attribute)

    • compound (複合段落)

  • 特殊表：

    • table (見出し付き表)

    • csv-table (読点区切り値から生成された表)

    • list-table (リストリストから生成された表)

  • 特別指示：

    • raw (元のターゲットフォーマット·マークを含む)

    • include (別のファイル内のreStruredTextを含む)-Sphinxにおいて、絶対的にファイルパスを含むことが与えられた場合、この命令は、ソースディレクトリに対してものとみなされる。

    • class (次の要素にクラス属性を割り当てる) 1

  • HTML詳細：

  • 影響値上げ：

    • default-role (新しいデフォルト·ロールの設定)

    • role (新しい役割の作成)

    これらは各ファイルのみなので、Sphinxのツールを使用して設定したほうがいいです default_role それがそうです。

警告

Do not use the directives sectnum, header and footer.

Sphinxが追加したコマンドを紹介した 指令 それがそうです。

基本的に、命令は名前、パラメータ、オプション、および内容から構成される。(この用語は、カスタム命令を記述する次章で使用されることを覚えておいてください。)この例では、：

.. function:: foo(x)
              foo(y, z)
   :module: some.module.name

   Return a line of text input from the user.

function コマンド名です。ここでは、2つのパラメータ、1行目および2行目の残りの部分、および1つのオプションを与える module (ご覧のように、オプションはパラメータの直後の行で与えられ、コロンによって表されます)。オプションは指示の内容と同じレベルに格納されなければならない。

命令内容は、空行の直後にあり、命令startに対して格納される。

影像.

RESTサポートイメージコマンド (ref )、使い方は以下の通りです。

.. image:: gnu.png
   (options)

Sphinxで使用される場合、与えられたファイル名(ここでは gnu.png )ソースファイルに対して、または絶対的でなければならず、これは、上位ソースディレクトリに対してであることを意味する。例えば、ファイルは sketch/spam.rst この写真を参考にしてもいいです images/spam.png として ../images/spam.png あるいは…。 /images/spam.png それがそうです。

Sphinxは、建物出力ディレクトリのサブディレクトリに画像ファイルを自動的にコピーする(例えば、 _static HTMLが出力するディレクトリ。)

画像サイズのオプションを説明する (width そして height )は、以下に示すように、サイズが単位または単位が画素でない場合、画素をサポートする出力チャネルの所与のサイズのみを考慮する。その他の単位(例えば pt 点)はHTMLおよびLaTeX出力(後者の代わりに使用される)に使用される pt vt.から. bp これはタークス単位なので 72bp=1in ）。

Sphinxは標準docutilsアクションを拡張し、拡張子として星番号を使用することを許可します：

.. image:: gnu.*

そして、Sphinxは、提供されたパターンに一致するすべての画像を検索し、それらのタイプを決定する。そして、各建設者はこれらの候補の中から最高のイメージを選択する。例えばファイル名が gnu.* 書類を二つ出した gnu.pdf そして gnu.png ソースコード木に存在する場合，LaTeXビルダは前者を選択し，HTMLビルダは後者を選択する.サポートされるイメージタイプと選択優先度は 建設者. それがそうです。

画像ファイル名にスペースは含まれていないことに注意してください。

バージョン 0.4 で変更: スター番号で終わるファイル名のサポートが追加されています。

バージョン 0.6 で変更: 画像経路は、現在、絶対経路であってもよい。

バージョン 1.5 で変更: LaTeXターゲットサポートピクセル(デフォルト) 96px=1in ）。

脚注

脚注についてはご参照ください (ref )、使用 [#name]_ 脚注位置をマークし，文書底の“脚注”見出しの後に脚注本文を付加すると，以下のようになる.

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

脚注を明示的に番号付けすることもできます ([1]_ )または名前なしの自動番号脚注を使用する ([#]_ ）。

引用文.

標準REST引用文 (ref )と、それらが“グローバル”であること、すなわち、すべての文書からすべての引用文を参照することができる追加の特徴がある。これらは以下のように使用される：

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] Book or article reference, URL or whatever.

引用用法は脚注用法と類似しているが，ラベルは数字や # それがそうです。

代わる

RESTは“代替”をサポート (ref )であり、これらは、テキスト中で参照されるテキストおよび/またはタグ付きセグメントである |name| それがそうです。これらの定義は、以下に示すように、明示的なフラグブロックを有する脚注と同様である。

.. |name| replace:: replacement *text*

あるいはこれです：

.. |caution| image:: warning.png
             :alt: Warning!

ご参照ください reST reference for substitutions もっと細かいことを知っています。

すべての文書の代わりに何らかの置換を使いたい場合は、入れてください rst_prolog あるいは…。 rst_epilog または、それらを別個のファイルに入れ、それらが使用されるすべての文書に含まれる。 include 指令する。(Sphinxが独立文書として使用することを回避するために、他のソースファイルとは異なるファイル拡張子をファイルを含むために提供することを確認してください。)

Sphinxはいくつかのデフォルト置換を定義していますので、参照してください 代わる それがそうです。

評論

有効なタグ構造ではない各明示的フラグブロック(上の脚注のような)は注釈とみなされる. (ref ）。例えば：

.. This is a comment.

注釈が複数行の注釈を形成し始めた後にテキストをインデントすることができます：

..
   This whole indented block
   is a comment.

   Still in the comment.

HTMLメタデータ

♪the meta 指令 (ref )HTMLの指定を許可する metadata element Sphinx文書ページの。例えば、命令：：

.. meta::
   :description: The Sphinx documentation builder
   :keywords: Sphinx, documentation, builder

以下のHTML出力を生成する：

<meta name="description" content="The Sphinx documentation builder">
<meta name="keywords" content="Sphinx, documentation, builder">

また，SphinxはMETAコマンドで指定されたキーワードを検索インデックスに追加する.だから、 lang 属性は，メタ要素の属性を考える.例えば、命令：：

.. meta::
   :keywords: backup
   :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
   :keywords lang=de: bittediesenkeyfinden

以下の単語を異なる言語配置を持つ生成された検索インデックスに追加する：

  • pleasefindthiskey, pleasefindthiskeytoo to English builds;

  • bittediesenkeyfinden 至る ドイツ語. 構築しています

  • backup 全ての言語のバージョンを構築することができます

ソースコード.

RESTに破折番号や著作権記号などの特殊な文字が含まれる最も簡単な方法は，それらをUnicode文字に直接書き込むことであるため，コードを指定しなければならない.デフォルトでは、Sphinx偽ソースファイルはUTF-8で符号化されています。使用することができます。 source_encoding 値を配置する。

捕まえたぞ

REST文書を作成する際には一般的に問題があります

  • 内接マークの区切り： 以上のように，連結タグ範囲は周囲のテキストとの間に非単語文字区切りを用いる必要があり，逆スラッシュ変換スペースを用いてこの問題を解決しなければならない.見 the reference 詳細です。

  • ネストされた内部接続マークはありません このようなものは *see :func:`foo`* 不可能です。

脚注

1

デフォルトドメインには class 指示は、その指示が追跡されるだろう。そこでライオンの顔像は rst-class それがそうです。