rst2json 0.5.1

安装

rst2json 需要 Python 3.7 或更高版本。只需使用 pip 为 Python 3 安装 rst2json 和其依赖项（您有 pip 吗？）

python3 -m pip install rst2json

命令行使用

rst2json 提供了一个名为 rst2json 的单个命令，该命令将输入的 reStructuredText 文档转换为组织成 JSON 对象的标记。

rst2json [--format <FMT>] [<docutils options>] [<infile> [<outfile>]]

目标标记格式通过 -f 或 --format 选项指定。有效值（不区分大小写）如下：

html（默认值）

html4 的别名。当 Docutils 最终将 rst2html.py 更改为生成 HTML 5 输出而不是 HTML 4 时，此别名也将相应更新为指向 html5。

html4

基于用于 rst2html4.py 的 Docutils 编写器的 HTML 4 / XHTML 1.0 输出。必须将 CSS 样式表（例如 Docutils 一起分发的 html4css1.css 样式表）添加到最终文档中，以便正确渲染所有内容。

html5

基于用于 rst2html4.py 的 Docutils 编写器的 HTML 5 输出。必须将 CSS 样式表（例如 Docutils 一起分发的 minimal.css 和 plain.css 样式表）添加到最终文档中，以便正确渲染所有内容。

latex

基于用于 rst2latex.py 的 Docutils 编写器的 LaTeX 输出。

latex2e

latex 的别名。

xelatex

xelatex 的别名。

xelatex

基于用于 rst2xetex.py 的 Docutils 编写器的 XeLaTeX 输出。

除了 --format 选项外，rst2json 命令还接受 Docutils 的 rst2html4.py、rst2html5.py、rst2latex.py 和 rst2xetex.py 命令接受的所有选项，并且可以通过与相应 Docutils 命令相同的方式通过 Docutils 配置文件 进行配置。还接受 rst2json 特定的选项；有关详细信息，请参阅“配置选项”。

库使用

rst2json.core.rst2json(source, format='html', options=None, config_files=None, destination_path=None)

配置选项

Text before sections, except after C.

Section 1
=========

.. _foo:

Lorem ipsum yadda yadda yadda.

Section 2
=========

'Twas brillig, and the slithy toves did gyre and gimble in the wabe.

Section 2.1
-----------

.. _bar:

All mimsy were the borogoves, and the mome raths outgrabe.

Section 2.1.1
~~~~~~~~~~~~~

Beware the Jabberwock, my son!

{
    "intro": "<p>Text before sections, except after C.</p>",
    "sections": [
        {
            "title": "Section 1",
            "ids": ["section-1"],
            "depth": 1,
            "body": "<p id=\"foo\">Lorem ipsum yadda yadda yadda.</p>\n"
        },
        {
            "title": "Section 2",
            "ids": ["section-2"],
            "depth": 1,
            "body": "<p>'Twas brillig, and the slithy toves did gyre and gimble in the wabe.</p>\n<div class=\"section\" id=\"section-2-1\">\n<h2>Section 2.1</h2>\n<p id=\"bar\">All mimsy were the borogoves, and the mome raths outgrabe.</p>\n<div class=\"section\" id=\"section-2-1-1\">\n<h3>Section 2.1.1</h3>\n<p>Beware the Jabberwock, my son!</p>\n</div>\n</div>"
        }
    ]
}

{
    "intro": "<p>Text before sections, except after C.</p>",
    "sections": [
        {
            "title": "Section 1",
            "ids": ["section-1"],
            "depth": 1,
            "intro": "<p id=\"foo\">Lorem ipsum yadda yadda yadda.</p>",
            "sections": []
        },
        {
            "title": "Section 2",
            "ids": ["section-2"],
            "depth": 1,
            "intro": "<p>'Twas brillig, and the slithy toves did gyre and gimble in the wabe.</p>",
            "sections": [
                {
                    "title": "Section 2.1",
                    "ids": ["section-2-1"],
                    "depth": 2,
                    "body": "<p id=\"bar\">All mimsy were the borogoves, and the mome raths outgrabe.</p>\n<div class=\"section\" id=\"section-2-1-1\">\n<h3>Section 2.1.1</h3>\n<p>Beware the Jabberwock, my son!</p>\n</div>"
                }
            ]
        }
    ]
}

JSON输出结构

以下描述将字符串分为以下类型

• 渲染字符串是包含目标格式（HTML或LaTeX）中标记的字符串。渲染字符串将去除前导和尾随换行符。

• 去除字符串是其中具有格式特殊意义的字符被转义但所有其他标记已被删除的字符串；此外，在具有相应渲染字符串的去除字符串中，换行符和制表符被替换为空格字符。

  例如，在HTML中，如果content.title是"<i>War &amp; Peace</i>"，那么content.title_stripped将是"War &amp; Peace"。

• 无资格（既不是渲染也不是去除）的字符串不应包含任何特殊字符。

rst2json的输出是一个包含以下字段的JSON对象

content对象

输入文档转换为目标格式并拆分为以下字段

title渲染字符串或null

文档标题，如果启用 doctitle_xform，则来自单个顶级节标题，如果没有指定标题或未启用 doctitle_xform，则为 null。

subtitle渲染字符串或 null

文档副标题，如果启用 doctitle_xform，则来自文档标题后的单个二级节标题，如果没有指定副标题或未启用 doctitle_xform，则为 null。

title_stripped去除标记的字符串或 null

title 字段，但移除了非转义标记。此字段可用于填充 HTML 文档的 <title> 标签。

subtitle_stripped去除标记的字符串或 null

subtitle 字段，但移除了非转义标记。此字段可用于填充 HTML 文档的 <title> 标签。

document_ids字符串列表

所有分配给解析的 document 节点的 ID 列表。这些 ID 应使用 HTML 的 id 属性或 (Xe)LaTeX 的 \label 命令附加到最终模板文档的最顶层或接近顶层的结构。

document_classes字符串列表

附加到解析的 document 节点的类列表。

subtitle_ids字符串列表

分配给文档副标题的所有 ID 列表，如果没有副标题则为空列表。这些 ID 应使用 HTML 的 id 属性或 (Xe)LaTeX 的 \label 命令附加到模板副标题。

subtitle_classes字符串列表

附加到文档副标题的类列表，如果没有副标题则为空列表。

authors渲染字符串列表

在 :Author: 和/或 :Authors: 参考文献字段 中指定的所有作者列表，按输入顺序排列。

header渲染字符串或 null

来自文档的 header:: 指令的渲染内容，如果没有此类指令则为 null。不包括用作页眉的标记。

footer渲染字符串或 null

来自文档的 footer:: 指令的渲染内容，如果没有此类指令则为 null。不包括用作页脚的标记。

docinfo对象列表

文档的 参考文献字段（不包括奉献词 & 摘要）按输入顺序排列，每个字段都表示为一个具有以下字段的对象

type字符串

对于已注册字段，这是表示字段的 Docutils 节点类的名称——即字段的小写英文名称（例如，"author"）。对于未注册字段，这是字符串 "field"。

name渲染字符串

对于已注册字段，这是文档语言中字段的名称（例如，"作者"）。对于未注册字段，这是输入中出现的字段名称。

value

当 type 为 "authors"（复数）时，这是一个作者名称的渲染字符串列表。对于所有其他 type 值，这是一个渲染字符串。

注意，当 type 为 "address" 时，value 中的空白是重要的，并且 value 应该被 <pre> 标签或类似标签包裹。

value_stripped

这是一个 value 字段，但移除了非转义标记。当 type 为 "authors"（复数）时，这是一个去除空格的字符串列表。对于所有其他 type 值，这是一个去除空格的字符串。此字段可用于填充 <meta> 标签的 content 属性。

classes字符串列表

附加到字段上的类列表。通常，对于已注册字段，此列表为空，而对于未注册字段，它包含一个等于字段名称转换为有效类标记的单个元素。此字段可用于设置包含渲染字段的 HTML 结构的 CSS 类。

abstract渲染字符串或 null

文档 :Abstract: 字段的渲染内容，或者如果不存在此类字段，则为 null。不包括摘要标题和封装块。

dedication渲染字符串或 null

文档 :Dedication: 字段的渲染内容，或者如果不存在此类字段，则为 null。不包括献词标题和封装块。

body渲染字符串

前导内容之后文档其余部分的渲染内容。只有当 split_section_level（参见“配置选项”）为 0 时，此字段才存在。

intro渲染字符串

前导内容之后、第一部分之前的内容。只有当 split_section_level 不为 0 时，此字段才存在。

sections对象列表

文档顶层部分的列表，每个部分由以下字段的对象表示。只有当 split_section_level 不为 0 时，此字段才存在。

title渲染字符串

部分标题

subtitle渲染字符串或 null

部分副标题，如果启用了 sectsubtitle_xform，则来自部分标题之后的单独第二级标题，或者如果没有指定副标题或未启用 sectsubtitle_xform，则为 null。

title_stripped去除空格的字符串

去除非转义标记的 title 字段

subtitle_stripped去除标记的字符串或 null

去除非转义标记的 subtitle 字段

ids字符串列表

所有分配给解析的section节点的ID列表。

classes字符串列表

附加到解析的section节点的类列表。

subtitle_ids字符串列表

分配给章节副标题的所有ID列表，如果没有副标题则为空列表。

subtitle_classes字符串列表

附加到章节副标题的类列表，如果没有副标题则为空列表。

toc_backref字符串或 null

如果此章节在带有回链的目录表中列出，此字段将等于目录表中回链应指向的位置的ID；否则，它将为 null。如果章节在多个带有回链的目录表中列出，此字段中最终出现的值由Docutils实现定义。

number去除空格的字符串或 null

由 sectnum:: 指令生成的章节编号，如果没有为章节生成编号则为 null。

depth整数

章节的深度：顶级章节为1，子章节为2，次子章节为3等。

body渲染字符串

章节的渲染内容。只有当 split_section_level 等于章节深度时，此字段才存在。

intro渲染字符串

章节中第一个子章节之前的渲染内容。只有当 split_section_level 为负数或大于章节深度时，此字段才存在。

sections对象列表

此章节顶级子章节的列表，每个子章节都表示为具有与 content.sections[] 相同模式的对象。只有当 split_section_level 为负数或大于章节深度时，此字段才存在。

trailing_transition对象或 null

如果此章节与下一个章节之间存在过渡，则此字段将是一个具有字段 ids（分配给过渡的ID列表）和 classes（分配给过渡的类列表）的对象；否则，此字段将为 null。请注意，在解析的文档树中，章节间过渡仅发生在相同深度的连续章节之间。

注意：据本库作者判断，reStructuredText文档无法生成包含文档标题、docinfo、页眉、页脚、摘要、献词或章节标题节点具有任何ID或类的doctree，也无法生成任何docinfo字段节点具有任何ID。因此，rst2json不输出此类值的任何字段。

meta对象

关于输入文档和 rst2json 处理的数据字典，包含以下字段

format字符串

目标标记格式的名称："html4"、"html5"、"latex" 或 "xelatex"。

split_section_level整数

为 split_section_level 选项设置的值（见“配置选项”）。负值转换为-1。

title去除空格的字符串或 null

文档的元数据标题。默认情况下，它与 content.title_stripped 相等，但可以被 title:: 指令或 title 配置选项覆盖。如果没有设置这些选项，则该字段为 null。

请注意，如果通过 title:: 指令或 title 配置选项设置标题，则其中任何 reStructuredText 标记都将不会处理（尽管特殊字符仍然会被转义）。例如，在您的输入文档中包含 .. title:: *War & Peace*，在输出 HTML 时将生成 meta.title 值为 "*War &amp; Peace*"，星号保持原样，而和号会被转义。

sourcestripped string

输入文件的名称/路径。如果无法确定名称，则这将是一个空字符串。

languagestring

文档语言的语言代码，如通过 language_code 配置选项设置

docutils_versionstring

用于生成输出的 Docutils 版本

rst2json_versionstring

用于生成输出的 rst2json 版本

generatorstripped string

形式为 "rst2json {version} ({url}), Docutils {version} ({url})" 的字符串

htmlobject

一个字典，包含要插入最终 HTML 文档头部的字符串。此对象仅在目标格式为 HTML4 或 HTML5 时出现。该字典的字段如下

math_requiresrendered string

如果输入文档包含任何 math:: 指令或 :math: 角色的话，这将是一个字符串，包含添加到 HTML 文档头部以支持这些角色的适当标记；如果没有这样的指令或角色，则这是一个空字符串。

当设置时，此字段的值由 math_output 配置选项确定。当设置为 html 时，它是一个 <link> 标签或一个 <style> 块（由 embed_stylesheet 配置选项确定）以启用作为选项参数传递的样式表；当设置为 mathjax 时，它是一个指向作为选项参数传递的路径或 URL 的 <script> 标签。当 math_output 为 mathml 或 latex 时，math_requires 字段为空字符串，因为不需要向 HTML 文档添加任何内容。

meta_tagsrendered string

包含使用 meta:: 指令添加到文档的所有 <meta> 标签的字符串。如果没有提供 meta:: 指令，则这是一个空字符串。

latexobject

一个字典，包含要插入最终 (Xe)LaTeX 文档前导部分的字符串。此对象仅在目标格式为 LaTeX 或 XeLaTeX 时出现。该字典的字段如下

languagestring

文档语言的名称（通过 language_code 配置选项设置），以 Babel 识别的格式。如果 Docutils 不识别该语言，则此字段将为空字符串。请注意，当语言不是英语时，latex.requirements 已包含适当的 \usepackage[LANGUAGE]{babel} 命令；此字段的目的是能够在文档选项中设置语言。

requirements渲染的字符串

所需的软件包和设置，主要包含 \includepackage 命令，这些命令用于在 content.body 中的标记。在一个模板化的（Xe）LaTeX 文档中，这应该在序言的早期部分。

fallbacks渲染的字符串

Docutils 在正文中使用的各种自定义命令的回退定义（使用 \providecommand* 声明）。这些定义可以通过在 latex.fallbacks 发生前在序言中定义同名命令来覆盖。在一个模板化的（Xe）LaTeX 文档中，这应该在 latex.requirements 之后和任何自定义序言命令之后。

pdfsetup渲染的字符串

包含和设置 hyperref 软件包。在一个模板化的（Xe）LaTeX 文档中，这应该在序言的末尾。

system_messages对象列表

在处理输入文档过程中生成的系统消息列表。通常，系统消息除了报告到 stderr 之外，还会嵌入到输出中，但 rst2json 将它们从正文中删除并放置在此列表中。每个系统消息都表示为一个对象，具有以下字段

level整数

系统消息级别作为从 0（最轻微）到 4（最严重）的整数

type字符串

系统消息级别的名称。系统消息级别的名称及其对应的整数值如下

类型	级别
DEBUG	0
INFO	1
WARNING	2
ERROR	3
SEVERE	4

sourcestripped string

生成消息的输入文件名称。如果无法确定名称，则此字段将为空字符串。

line整数或 null

生成消息的输入文件行，或如果无法确定则为 null

body渲染字符串

消息本身

ids字符串列表

system_message 节点的 ID。如果解析的文档树包含一个封装生成系统消息的标记的 problematic 节点，则渲染的 problematic 节点将通过在 ids 中定位 ID 来链接到该系统消息。

如果系统消息包含在模板文档中，则应使用 HTML 的 id 属性或（Xe）LaTeX 的 \label 命令将 ID附加到结构中。

backrefs字符串列表

如果解析的文档树包含一个封装生成系统消息的标记的 problematic 节点，则 backrefs 将包含渲染的 problematic 节点的 ID，可用于创建文档内链接。

id_sections对象

此对象仅在输出中显示，当split_section_level（见“配置选项”）不为0时。它是一个映射，其中每个键是出现在渲染文档正文中的ID，相应的值是该键ID出现的最深分割对象的第一ID。章节间过渡的ID映射到存储其trailing_transition字段的章节ID。出现在content.intro中的ID映射到特殊字符串"$intro"。顶级章节的ID不包含在此映射的键中，但更深章节的ID包含在内。

当输出用于为每个章节创建单独的模板文档时，可以使用此字段重写文档间链接。

例如，考虑以下文档

Section 1
=========

.. _foo:

Lorem ipsum yadda yadda yadda.

Section 2
=========

'Twas brillig, and the slithy toves did gyre and gimble in the wabe.

Section 2.1
-----------

.. _bar:

All mimsy were the borogoves, and the mome raths outgrabe.

Section 2.1.1
~~~~~~~~~~~~~

Beware the Jabberwock, my son!

如果以split_section_level为1进行处理，则id_sections将如下所示

{
    "foo": "section-1",
    "section-2-1": "section-2",
    "bar": "section-2",
    "section-2-1-1": "section-2"
}

如果以split_section_level为2进行处理，则id_sections将如下所示

{
    "foo": "section-1",
    "section-2-1": "section-2",
    "bar": "section-2-1",
    "section-2-1-1": "section-2-1"
}

将split_section_level增加至此点以上或使其为负数将不会有任何进一步的效果。