用来写markdown的文件了，写了几天有点小感触记下来
基础安装
- 需要安装vscode的python组件
python install
设置PATH参考: https://www.javadrive.jp/python/install/index3.html
pip install指令以及需要安装的内容
pip install sphinx
pip install sphinx_rtd_theme
pip install sphinx_fontawesome
pip install commonmark recommonmark
pip install docutils doc8
pip install rstcheck
- vscode的文件预览插件安装（二选一即可）
完整版reStructuredText，可看到目录预览、内容文字图片预览、以及文字颜色等CSS样式的预览，但是经常出错，非常慢，不稳定：reStructuredText
简易版RST Preview，可以看到内容文字图片的预览，但是目录以及部分样式设定效果为报错，比较快和稳定：RST Preview
使用参考文档：https://sublime-and-sphinx-guide.readthedocs.io/en/latest/index.html
目录构建
目录需要用toctree创建，同时可以在当前rst文件加入其它需要的文字以及内容
.. toctree::
:caption: Contents:
:maxdepth: 3 // 最多目录阶层
xxxx-1.rst // 目录内容可直接引用
xxx/xxxx-2.rst // 可跨目录引用，比如../../xx/xx/index.rst
章节
有四阶目录显示方式，根据逻辑进行选择，如果章节部分太多，可以构建多重目录进行分摊降级（多用几个toctree）
=====================
セクション(レベル１)
=====================
// 一阶目录（最大的）例如：Title
レベル２
========
// 二阶目录 Chapter （章）例如：1. 、 2. 、 3.
レベル３
--------
// 三阶目录 Section（节）例如：（1）、（2）、（3）
レベル４
^^^^^^^^
// 四阶目录 Subsection（小节） 没有特别显示，除了加粗
文字
直接粘贴，断句用回车隔开，可以隔断文字（段落元素）
// 段落表示如下，行与行之间间隔会大一些，使用的应该是类似el-row的margin-bottom高度
xxxxxxx
xxxxxxx
// 行高表示为长句的自动换行，使用的应该是lineheight的间隔，会根据页面宽度自动换行
xxxxxxxxxxxxxxxxx
文字带标点（ - XXXX / * XXXX）效果如下
- XXXX
数字list部分（ 1. XXXX ）效果如下
- XXXX
注释部分（可以直接用两个空格，带缩进，略微参考如下效果，可配合全角空格做一些多余缩进）
| XXXX
表格
由于使用vscode的时候直接线条歪楼（英文字符和中文等字符本身的一些问题），我是在一个txt里面画完之后再帖进去，基本都OK
表格这边基本就是原样画图，但是内部细节不可过多，目前会用简单表格和普通表格
// 简单表格1（带竖线为跨行）
========= ==================
simple content
title | content
|
========= ==================
// 简单表格2（最后一位可以超线，会自动换行）
========= ==================
title1 content可以超出线框不需要另外修改，会自动换行
========= ==================
// 简单表格3 内有多个标题也可以拆分
=============== ==================
title1 title2 content
------- ------- ------------------
title 1 + 2 content
=============== ==================
// 普通表格（可以表格套表格，也可以加入图片，比较常用，根据最新要求要减少使用）
+------------------------------------+----------------------------------------------------------------------+
| tabel-header-1 | tabel-header-2 |
+====================================+======================================================================+
| tabel-body-column-1 | tabel-body-column-2 |
| | |
| | +-----------------------+----------------------------------------+ |
| | | small-table-1 | small-table-content-1 | |
| | +-----------------------+----------------------------------------+ |
| | | small-table-2 | small-table-content-2 | |
| | +-----------------------+----------------------------------------+ |
| | | small-table-3 | small-table-content-3 | |
| | +-----------------------+----------------------------------------+ |
| | |
+------------------------------------+----------------------------------------------------------------------+
| tabel-body-column-1 | tabel-body-column-2 |
+------------------------------------+----------------------------------------------------------------------+
| | |
| tabel-body-column-1（前带缩进） | - tabel-body-column-2-point-1 |
| | |
| | 正常缩进内容 |
| | |
| | - tabel-body-column-2-point-2 |
| | |
| | - tabel-body-column-2-point-3 |
+------------------------------------+----------------------------------------------------------------------+
// 带图片表格（image部分为引入语法，.. image:: 都是英文输入，且需要前空一行，才能起效用，每行就一个标识符可以识别，其他都有点问题，也可能是我还不会用）
+--------------------------------------+------------------------------------------------------------+
| | システム管理者に確認した **テナントコード** を入力します。 |
| .. image:: images/pcTenantCode.png | |
| | |
+--------------------------------------+------------------------------------------------------------+
普通表格参考效果
除了直接使用符号进行表格绘制，还能通过csvlist、listtable等方法进行表格绘制
其他表格引入方式
.. csv-table::
:header: table-header-1, table-header-2 // 表头
:widths: 5, 20 // 两列的宽度
"table-column-1", "table-column-2"
// 通过双引号包含数据，用逗号隔开，每个逗号都是一列，作为csv-table内容的补充，需要注意前面空格对齐
.. csv-table:: table-name // 表格名称
:header: table-header-1, table-header-2 // 表头
:widths: 5, 15 // 两列的宽度
// 表格内容↓，用逗号分隔，双引号为内容
"head", "header-content"
"body", "body-content"
没有name的table显示效果参考
带name的table显示效果参考
不完整表格
.. csv-table::
:header: 项目, 内容, 参考
:widths: 5, 20, 10
"项目一", "| 内容一
| ・内容一·point-1
| ・内容一·point-2
| ・内容一·point-3
| ・内容一·point-4", ""
"项目二", "内容二 ", ""
"项目三", "| 内容一·第一行
| 内容一·第二行", "参考一"
"项目四", "内容一 :ref:`引用<ref-menu>` ", "参考二"
|
|
不完整表格实际效果
由于使用简体版，不支持ref的实际效果演示，所以会报错，但是在实际使用中没有任何问题
属性
可以用css文件进行样式修改（待继续研究）
.. table::
:class: XXXX
嵌入图片
// 图片可添加属性如下（大图片引用常见手法）
.. image:: funny.gif
:height: 100px
:width: 100px
:alt: funny cat picture
:align: center</pre>
:scale: 50%
// icon等小图标添加属性如下（行内可直接显示，附带属性看齐大图片）
.. |Substitution Name| image:: path/filename.png
:width: 400
:alt: Alternative text
|Substitution Name| xxxxxx
多个图片不连贯加入分隔
.. image:: images/pcProcessTaskTodoFinal.png
:width: 600px
|
.. image:: images/pcProcessTaskTodoFinalLog.png
:width: 650px
嵌入代码:
.. code:: python // 此后是源代码
def say_hello():
print 'Hello, ReST'
if __name__ == '__main__':
say_hello()</pre>
嵌入链接
百度 `URI: <https://www.baidu.com/>`_ 链接引入样式
猜测结构：`网站名字或者keyword<url>`_，其中下划线为关门符号，必须有，不然不生效，名称跟url中间没有空格
直接使用链接，则可以直接贴网站地址
- 百度 URI: https://www.baidu.com/
嵌入tip等
可以插入图片、链接等等形式，注意引用格式即可
.. note::
`Tips的使用百度案例 <https://www.baidu.com/>`_ 同样在url后需要有'_'，才可以生效。
.. tip:: // 注釈
.. important::
.. caution:: // 注意
.. warning::
// 具体内容与标签中间必须空一行，原先是英文表示，但是现在都是日文表示了（这里是因为跟着浏览器的默认显示语言），意思还是一样的
xxxxxx
已知的几种引用图示效果参考
// 文件引用（全文跳转，相对url）
:doc:`../../page-management/create-page/index`
:doc:`title-name<name>`
// 部分引用（创造标题内容后跳转）
:ref:`引用参考<ref-menu>`
// 被引用部分格式参考↓
.. _ref-menu:
===================
xxxxxx
===================
xxxxxx
导航跳转
可以设定自定义对象，包含内容后，用ref进行跳转 :ref:对象名字<对象命名的内容>，需要有关门部分
.. _edit-error-settings:
================================
导航跳转案例一
================================
| 不重要的内容…… :ref:`削除<delete-error-settings>` 不重要的内容……
| 多个使用记得需要用空格与正文隔开 :ref:`作成<create-error-settings>` 引用部分在实际情况与url效果一般
| 只会显示<>前的标题文字内容
可以包含多重结构
================================
.. image:: images/edit-error-settings.png
:scale: 100
|
|
// ↑ 多个引用之间需要用关门分隔
.. _delete-error-settings:
================================
导航跳转案例二
================================
在跳转内容中同时也可以引用其他，所以格式相同 :ref:`edit-error-settings` 确保自身对应不出错
补充说明
================================
可以不使用 `标题<实际命名>` 的格式，直接写链接也是可以的，如上↑
.. image:: images/delete-error-settings.png
:scale: 60
|
|
// 整块内容结束了一定要记得关门，是两个丨，如↑
特殊符号
带颜色的标题写法参考（_static/customized.css里写css）：
实际效果参考
.. role:: color-circle-orange
:class: color-circle-orange
:color-circle-orange:`❶`
:color-circle-orange:`❷`
:color-circle-orange:`❸`
:color-circle-orange:`❹`
:color-circle-orange:`❺`
:color-circle-orange:`❻`
:color-circle-orange:`❼`
:color-circle-orange:`❽`
:color-circle-orange:`❾`
:color-circle-orange:`❿`
:color-circle-orange:`⓫`
:color-circle-orange:`⓬`
:color-circle-orange:`⓭`
其他细节
- 空格居中暂时用的是全角空格，多空几个才能看到效果
- 全角空格可以出段首缩进效果，但是只有纯文字才能奇效
- 所有命令段都需要回车来实现，除了部分引入的内容，行元素的修饰符只会生效一个
- 转义符“\”
- 可以通用简易css效果的，具体还需要研究，但是我是简体预览版，案例不好做，待补充
- 为了效果好，最好写死图片宽度，除了dialog、messagebox等特殊的大小
- table默认stripe效果
- table-header默认粗体
- 行内图片/icon引用感觉是以图片本身大小为准，不太倾向标准行的大小
