reStructuredText の簡潔な syntax_html/css_WEB-ITnose

https://github.com/xunxuny/zh-sphinx-doc/blob/master/rest.rst

この章では reStructuredText (reST) を紹介します

の概念と構文。reST

はシンプルで実用的なマークアップ言語と考えられているため、学習にそれほど時間はかかりません。

段落 (ref becdcb2dc349c8d8b2e612d45c44a449) は、reST ファイルの基本モジュールです。

段落は、Python と同様に、空白行で区切られたテキストのセクションです。 reST の演算子

であるため、同じ段落内の行はすべて左揃えになります。

インライン タグ

標準の reST インライン タグは非常に単純です。

アスタリスク: *text* は強調 (斜体)、

二重アスタリスク: **text** は強調 (太字)、
バックティック : テキスト コード
• アスタリスクとバッククォートは、テキスト内のインライン マークアップ記号と混同されやすいため、バックスラッシュ記号でエスケープできます。

マークアップの制限事項:

は互いに入れ子にすることはできません。

コンテンツの前後に空白を置くことはできません。このように *text* を記述するのは間違いです。コンテンツが必要な場合は
特殊文字で区切ります。次のようにバックスラッシュ エスケープを使用します。
• これらの制限は、将来のバージョンでは改善される可能性があります。 「解釈ロール」。これは、テキストを特定の方法で解釈できることを意味します。

Sphinx は、この方法でセマンティック マークアップと参照インデックスを提供します。演算子は

です。

標準 reST は次のルールを提供します:

* :durole:emphasis` - *emphasis** Strong として記述されます -

**strong*** リテラルとして記述されます -リテラル* 下付き文字 - 下付き文字*

上付き文字 – 上付き文字* タイトル参照 – 本、雑誌などのタイトル

詳細については、インラインマークアップを参照してください。

リストと引用

リスト タグ (ref 3ee7f52065fc38abe0bddbc741e8b734) の最も自然な使用法は次のとおりです:

単にアスタリスクとインデントを付けるだけです。段落の先頭に番号付きリストを使用することもできます。記号

も使用できます。 #シリアル番号を自動的に追加します:

リストはネストできますが、ネストする必要があります。空行で親リストから区切ります:

定義リスト (ref 557cfb47d376f4f8f3ef08bee4c96d48) 略語のみを使用します

* 这是* 一个列表  * 嵌套列表  * 子项* 父列表继续

行ブロック (ref 19a2d36be1a42331fee66568016612b0) は次のように区切ることができます:

术语 (term 文本开头行)   定义术语，必须缩进   可以有多段组成下一术语（term）   描述.

他にも便利なブロックがあります:

フィールド リスト (ref a48f2198a713b3dac939abbfe9c0e91e)

オプション リスト (ref リテラル参照モジュール (ref f0a81efa340647664b2ae88f6cdd74bc)

ドキュメント テスト モジュール (ref 0de4f4ab8f25a9835e3ba7c621345d93)
• ソース コード
リテラル コード ブロック (ref 016c615b167fe1e06196367d703605be) 段落の最後にマーク :: を使用します。
コード ブロックはインデントする必要があります (段落と同様、周囲のコード ブロックから分離する必要があります)。テキストは空行で区切ります):

この :: タグは非常にエレガントです:

スタンドアロンの段落として存在する場合、段落全体は表示されませんドキュメント内で

タグの前に空白がある場合、タグは削除されます。

这是一段正常文本. 下一段是代码文字::   它不需要特别处理，仅是   缩进就可以了.   它可以有多行.再是正常的文本段.

空白以外の文字が前にある場合、タグはコロンに置き換えられます。 >

したがって、上記の例のテキストの最初の段落は、「次の段落はコード テキストです:」になります。

• Table
は 2 種類のテーブルをサポートします。グリッド テーブル (ref
adc44295dbaef509975d79d382ee4d58) は簡単に記述できますが、いくつかの制限があります:

には複数の行が必要であり、最初の列要素は次のように別々の行に表示できません:

ハイパーリンク

+------------------------+------------+----------+----------+| 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             | ...        | ...      |          |+------------------------+------------+----------+----------+

外部リンク

`リンク テキストc1e6981ca4e23aee5a471013de4f0a87`を使用します。

リンク テキストが URL の場合、特別なマークは必要ありません。アナライザーはテキスト内のリンクまたは電子メール アドレスを自動的に検索します。

=====  =====  =======A      B      A and B=====  =====  =======False  False  FalseTrue   False  FalseFalse  True   FalseTrue   True   True=====  =====  =======

リンクとタグを分離して挿入できます。 -targets>)、次のように:

内部リンク

内部リンクは Sphinx 固有の reST ロールです。ref-role の章を参照してください。
セクション

セクションのタイトル (ref ) は二重上線記号 (または下線) の間にあり、記号の長さはテキストの長さより短くすることはできません:

段落里包含 `a link`_... _a link: http://example.com/

通常、タイトルのレベルを示す特別な記号はありませんが、Python ドキュメントの場合は次のように考えることができます:

• #及上划线表示部分
• *及上划线表示章节
• =, 小章节
• -, 子章节
• ^, 子章节的子章节
• ", 段落

当然也可以标记（查看 reST 文档),定义章节的层次，但是需要注意输出格式(HTML, LaTeX)所支持的层次深度 .

显式标记

显式标记”Explicit markup” (ref cb7aaf0f150a08c8d5b182c38919a770)用在那些需做特殊处理的reST结构中, 如尾注，突出段落，评论，通用指令.

显式标记以 ..开始，后跟空白符，与下面段落的缩进一样.

(在显示标记与正常的段落间需有空行，这听起来有些复杂，但是写起来会非常直观.)

指令

指令 (ref 7e86fe8fd715750b3d7401240c122c28) 是显式标记最常用的模块. 也是reST的扩展规则, 在 Sphinx 经常被用到.

文档工具支持以下指令:

• 警告: attention, caution, danger, error, hint, important, note, tip,warning 及通用标记 admonition. (大多数模式仅支持 “note” 及“warning” )
• 图像:
  • image (详情可看下面的 图像_ )
  • figure (有标题及可选说明的图像)
• 额外的主体元素:
  • contents 6c86273b6338b5508c27f28033702d91 (本地，仅是当前文件的内容表格)
  • container (自定义容器，用来生成HTML的 dc6dce4a544fdca2df29d5ac0ea9906b)
  • rubric (和文档章节无关的标题)
  • topic, sidebar (高亮显示的主体元素)
  • parsed-literal (支持内联标记的斜体模块)
  • epigraph (可选属性行的摘要模块)
  • highlights, pull-quote (有自己的类属性的摘要模块)
  • compound ( 复合段落)
• 专用表格:
  • table (有标题的表格)
  • csv-table (CSV自动生成表格)
  • list-table (列表生成的表格)
• 专用指令:
  • raw (包含原始格式的标记)
  • include (包含reStructuredText标记的文件) –在Sphinx中,如果包含绝对文件路径，指令会以源目录地址做为参照
  • class (将类属性指派给下一个元素) [^1]
• HTML 特性:
  • meta (生成HTML e8e496c15ba93d81f6ea4fe5f55a2244标签)
  • title (覆盖文档标题)

• 影响标记:

  • default-role (设置新的默认角色)
  • role (创建新的角色)

  如果仅有一个文件，最好使用 default_role.

设置不使用指令 sectnum, header 及 footer.

Sphinx 新增指令可查阅 sphinxmarkup.

指令有名字，参数，选项及内容组成.(记住这些，在下面一小节中自定义指令里会用到).来看一个例子:

.. function:: foo(x)              foo(y, z)   :module: some.module.name   返回用户输入的一行文本.

function是指令名字. 在第一行和第二行给出了两个参数, 及一个选项

module(如你所见，选项在参数后给出，由冒号引出).

选项必须与指令有一样的缩进.

指令的内容在隔开一个空行后，与指令有一样缩进.

图像

reST 支持图像指令 (ref dc0870658837139040642baa5555a380), 如下:

.. image:: gnu.png   (选项)

这里给出的文件名( gnu.png)

必须是源文件的相对路径，如果是绝对路径则以源目录为根目录. 例如，在文件

sketch/spam.rst引用图像 images/spam.png，则使用

../images/spam.png或者 /images/spam.png.

Sphinx 会自动将图像文件拷贝到输出目录的子目录里，( 输出HTML时目录为

_static)

图像的大小选项 ( width及 height) : 如果没有单位或单位为像素,

给定的尺寸信息仅在输出通道支持像素时才有用 ( 如输出LaTeX 没用).

其他单位在输出(如 pt)HTML、LaTeX 时被用到.

Sphinx 延伸了标准的文档化行为，只需在后面加星号:

.. image:: gnu.*

上面这样写，Sphinx 会搜索所有名字匹配的图像，而不管图像类型.

每个生成器则会选择最合适的图像. 一般，在源文件目录里文件名 gnu.*

会含有两个文件 gnu.pdf 和 gnu.png , LaTeX 生成器会选择前者，而HTML

生成器则匹配后者.

尾注

尾注 (ref 8df6dcf8cb5a57975d454ff1a2516a67), 使用 [#name]_标记尾注的位置,

尾注的内容则在文档底部红色标题”Footnotes”的后面 , 如下:

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_.. rubric:: Footnotes.. [#f1] 第一条尾注的文本... [#f2] 第二条尾注的文本.

你也可以使用数字尾注 ( [1]_) 或使用自动排序的( [#]_).

引用

支持标准的reST 引用 (ref fedcf96ca9e663f6e480aeb8196808f2) , 且新增了”global”特性,所有参考文献不受所在文件的限制. 如:

Lorem ipsum [Ref]_ dolor sit amet... [Ref] 参考文献, 书,URL 等.

引用的使用同尾注很相近，但是它们没有数字标签或以 #开始.

替换

reST 支持替换 “substitutions” (ref 61e7a9156929901c91ce35a2a049caa0),

有一小段文本或标记被关联到 |name|.

定义与尾注一样需有明确的标记块，如下:

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

或者:

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

详情查看reST reference for substitutions 61e7a9156929901c91ce35a2a049caa0 .

如果想在所有文档中使用这些替换, 需把它们放在 rst_prolog

或一个单独文件里， 然后在使用它们的文档文件里包含这个文件，包含指令

:rstinclude .

(请给出包含文件的扩展名，已区别于其他的源文件，避免Sphinx将其作为独立的文档文件.)

Sphinx 定义了一些默认的替换, 请查看 default-substitutions.

评论

有明确标记块但又不是有效的结构标记的标记 (像上面的尾注）都被视为评论(ref 3ffce9c08d8cb5cda8d499108bed573f). 例如:

.. 这是一个评论.

可以通过缩进产生多行评论:

..   这整个缩进块都是   一个评论.   仍是一个评论.

源编码

在reST使用Unicode字符可以容易的包含特殊字符如破折号，版权标志. Sphinx默认源文件使用UTF-8 编码; 你可以通过 source_encoding 的配置值改变编码.

常见问题

具体使用中可能会遇到一些问题:

• 内联标记的分离如上面所讲，内联标记需与周围的文本使用空格分隔, 内联标记内部则使用反斜线转义空格.查看详情:

  the

  reference

  .
• 内联标记不能嵌套像这样写 *see :func:`foo`*是不允许的.

Footnotes

[^1]: 当默认主域里包含指令 :rstclass , 这个指令将被隐藏 因此, Sphinx使用:rstrst-class.