欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  web前端

reStructuredText简明语法_html/css_WEB-ITnose

程序员文章站 2022-05-17 10:21:14
...
https://github.com/xunxuny/zh-sphinx-doc/blob/master/rest.rst

本章节介绍 reStructuredText (reST)

的概念和语法,为文档生成者提供足够的信息. reST

被认为是简单,实用的标记语言,因此学习它不会花太多时间.

段落

段落 (ref ) 是reST 文件的基本模块.

段落是由空行分隔的一段文本. 和Python一样, 对齐也是reST的操作符,

因此同一段落的行都是左对齐的.

内联标记

标准的reST 内联标记相当简单:

  • 星号: *text*是强调 (斜体),
  • 双星号: **text**重点强调 (加粗),
  • 反引号: text代码样式.

星号及反引号在文本中容易与内联标记符号混淆,可使用反斜杠符号转义.

标记需注意的一些限制:

  • 不能相互嵌套,
  • 内容前后不能由空白: 这样写 * text*是错误的,
  • 如果内容需要特殊字符分隔. 使用反斜杠转义,如: thisis\ *one*\ word.

这些限制在未来版本可能会被改善.

reST 也允许自定义 “文本解释角色”‘, 这意味着可以以特定的方式解释文本.

Sphinx以此方式提供语义标记及参考索引,操作符为 :rolename:`content.

标准reST 提供以下规则:

* :durole:emphasis` – 写成 *emphasis** strong – 写成

**strong*** literal – 写成 literal* subscript – 下标 *

superscript – 上标 * title-reference – 书、期刊等材料的标题

详情请查看 inline-markup .

列表与引用

列表标记 (ref ) 的使用最自然:

仅在段落的开头放置一个星号和一个缩进. 编号的列表也可以;也可以使用符号

#自动加序号:

* 这是一个项目符号列表.* 它有两项,  第二项使用两行.1. 这是个有序列表.2. 也有两项.#. 是个有序列表.#. 也有两项.

列表可以嵌套,但是需跟父列表使用空行分隔 :

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

定义列表 (ref ) :

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

一行仅能写一个术语.

引用段落 (ref ) 仅使用缩进(相对于周围段落)创建.

行模块 (ref ) 可以这样分隔 :

| 这些行| 在源文件里| 被分隔的一模一样.

还有其他有用的模块:

  • 字段列表 (ref )
  • 选项列表(ref )
  • 字面引用模块 (ref )
  • 文档测试模块 (ref )

源代码

字面代码块 (ref ) 在段落的后面使用标记 ::引出.

代码块必须缩进(同段落,需要与周围文本以空行分隔):

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

这个 ::标记很优雅:

  • 如果作为独立段落存在,则整段都不会出现在文档里.
  • 如果前面有空白,则标记被移除.
  • 如果前面是非空白,则标记被一个冒号取代.

因此上面的例子第一段文字将变为”下一段是代码文字:”.

表格

支持两种表格. 一种是 网格表格(ref

), 可以自定义表格的边框. 如下:

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

简单表格(ref ) 书写简单, 但有一些限制:

需要有多行,且第一列元素不能分行显示,如下:

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

超链接

外部链接

使用 `链接文本 `_可以插入网页链接.

链接文本是网址,则不需要特别标记,分析器会自动发现文本里的链接或邮件地址.

可以把链接和标签分开 (ref), 如下:

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

内部链接

内部链接是Sphinx特定的reST角色, 查看章节 ref-role.

章节

章节的标题 (ref ) 在双上划线符号之间(或为下划线),并且符号的长度不能小于文本的长度:

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

通常没有专门的符号表示标题的等级,但是对于Python 文档,可以这样认为:

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

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

显式标记

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

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

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

指令

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

文档工具支持以下指令:

  • 警告: attention, caution, danger, error, hint, important, note, tip,warning 及通用标记 admonition. (大多数模式仅支持 “note” 及“warning” )
  • 图像:
    • image (详情可看下面的 图像_ )
    • figure (有标题及可选说明的图像)
  • 额外的主体元素:
    • contents (本地,仅是当前文件的内容表格)
    • container (自定义容器,用来生成HTML的
      )
    • 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 标签)
      • 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 ), 如下:

      .. 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 ), 使用 [#name]_标记尾注的位置,

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

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

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

      引用

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

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

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

      替换

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

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

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

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

      或者:

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

      详情查看reST reference for substitutions .

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

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

      :rstinclude .

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

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

      评论

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

      .. 这是一个评论.

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

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

      源编码

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

      常见问题

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

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

        the

        reference

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

      Footnotes

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

      reStructuredText简明语法_html/css_WEB-ITnose

      声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn核实处理。

相关文章

相关视频


相关标签: reStructuredText简明语法

上一篇: 新书基础篇大纲调整

下一篇: 请问下这种可以用表单提交数据么_html/css_WEB-ITnose

推荐阅读