用來(lái)寫markdown的文件了，寫了幾天有點(diǎn)小感觸記下來(lái)
基礎(chǔ)安裝
- 需要安裝vscode的python組件
python install
設(shè)置PATH參考: https://www.javadrive.jp/python/install/index3.html
pip install指令以及需要安裝的內(nèi)容
pip install sphinx
pip install sphinx_rtd_theme
pip install sphinx_fontawesome
pip install commonmark recommonmark
pip install docutils doc8
pip install rstcheck
- vscode的文件預(yù)覽插件安裝（二選一即可）
完整版reStructuredText勋拟，可看到目錄預(yù)覽安寺、內(nèi)容文字圖片預(yù)覽、以及文字顏色等CSS樣式的預(yù)覽，但是經(jīng)常出錯(cuò)，非常慢在塔，不穩(wěn)定：reStructuredText
簡(jiǎn)易版RST Preview，可以看到內(nèi)容文字圖片的預(yù)覽虐拓，但是目錄以及部分樣式設(shè)定效果為報(bào)錯(cuò)心俗，比較快和穩(wěn)定：RST Preview
使用參考文檔：https://sublime-and-sphinx-guide.readthedocs.io/en/latest/index.html
目錄構(gòu)建
目錄需要用toctree創(chuàng)建傲武，同時(shí)可以在當(dāng)前rst文件加入其它需要的文字以及內(nèi)容
.. toctree::
:caption: Contents:
:maxdepth: 3 // 最多目錄階層
xxxx-1.rst // 目錄內(nèi)容可直接引用
xxx/xxxx-2.rst // 可跨目錄引用蓉驹，比如../../xx/xx/index.rst
章節(jié)
有四階目錄顯示方式，根據(jù)邏輯進(jìn)行選擇揪利，如果章節(jié)部分太多态兴，可以構(gòu)建多重目錄進(jìn)行分?jǐn)偨导?jí)（多用幾個(gè)toctree）
=====================
セクション(レベル１)
=====================
// 一階目錄（最大的）例如：Title
レベル２
========
// 二階目錄 Chapter （章）例如：1. 、 2. 疟位、 3.
レベル３
--------
// 三階目錄 Section（節(jié)）例如：（1）瞻润、（2）、（3）
レベル４
^^^^^^^^
// 四階目錄 Subsection（小節(jié)） 沒(méi)有特別顯示甜刻，除了加粗
文字
直接粘貼绍撞，斷句用回車隔開(kāi)，可以隔斷文字（段落元素）
// 段落表示如下得院，行與行之間間隔會(huì)大一些傻铣，使用的應(yīng)該是類似el-row的margin-bottom高度
xxxxxxx
xxxxxxx
// 行高表示為長(zhǎng)句的自動(dòng)換行，使用的應(yīng)該是lineheight的間隔祥绞，會(huì)根據(jù)頁(yè)面寬度自動(dòng)換行
xxxxxxxxxxxxxxxxx
文字帶標(biāo)點(diǎn)（ - XXXX / * XXXX）效果如下
- XXXX
數(shù)字list部分（ 1. XXXX ）效果如下
- XXXX
注釋部分（可以直接用兩個(gè)空格非洲，帶縮進(jìn)，略微參考如下效果蜕径，可配合全角空格做一些多余縮進(jìn)）
| XXXX
表格
由于使用vscode的時(shí)候直接線條歪樓（英文字符和中文等字符本身的一些問(wèn)題）两踏，我是在一個(gè)txt里面畫完之后再帖進(jìn)去，基本都OK
表格這邊基本就是原樣畫圖兜喻，但是內(nèi)部細(xì)節(jié)不可過(guò)多梦染，目前會(huì)用簡(jiǎn)單表格和普通表格
// 簡(jiǎn)單表格1（帶豎線為跨行）
========= ==================
simple content
title | content
|
========= ==================
// 簡(jiǎn)單表格2（最后一位可以超線，會(huì)自動(dòng)換行）
========= ==================
title1 content可以超出線框不需要另外修改朴皆，會(huì)自動(dòng)換行
========= ==================
// 簡(jiǎn)單表格3 內(nèi)有多個(gè)標(biāo)題也可以拆分
=============== ==================
title1 title2 content
------- ------- ------------------
title 1 + 2 content
=============== ==================
// 普通表格（可以表格套表格弓坞，也可以加入圖片隧甚，比較常用，根據(jù)最新要求要減少使用）
+------------------------------------+----------------------------------------------------------------------+
| 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（前帶縮進(jìn)） | - tabel-body-column-2-point-1 |
| | |
| | 正扯啥常縮進(jìn)內(nèi)容 |
| | |
| | - tabel-body-column-2-point-2 |
| | |
| | - tabel-body-column-2-point-3 |
+------------------------------------+----------------------------------------------------------------------+
// 帶圖片表格（image部分為引入語(yǔ)法戚扳，.. image:: 都是英文輸入，且需要前空一行族吻，才能起效用帽借，每行就一個(gè)標(biāo)識(shí)符可以識(shí)別，其他都有點(diǎn)問(wèn)題超歌，也可能是我還不會(huì)用）
+--------------------------------------+------------------------------------------------------------+
| | システム管理者に確認(rèn)した **テナントコード** を入力します砍艾。 |
| .. image:: images/pcTenantCode.png | |
| | |
+--------------------------------------+------------------------------------------------------------+
普通表格參考效果
除了直接使用符號(hào)進(jìn)行表格繪制，還能通過(guò)csvlist巍举、listtable等方法進(jìn)行表格繪制
其他表格引入方式
.. csv-table::
:header: table-header-1, table-header-2 // 表頭
:widths: 5, 20 // 兩列的寬度
"table-column-1", "table-column-2"
// 通過(guò)雙引號(hào)包含數(shù)據(jù)脆荷，用逗號(hào)隔開(kāi)，每個(gè)逗號(hào)都是一列懊悯，作為csv-table內(nèi)容的補(bǔ)充蜓谋，需要注意前面空格對(duì)齊
.. csv-table:: table-name // 表格名稱
:header: table-header-1, table-header-2 // 表頭
:widths: 5, 15 // 兩列的寬度
// 表格內(nèi)容↓，用逗號(hào)分隔炭分，雙引號(hào)為內(nèi)容
"head", "header-content"
"body", "body-content"
沒(méi)有name的table顯示效果參考
帶name的table顯示效果參考
不完整表格
.. csv-table::
:header: 項(xiàng)目, 內(nèi)容, 參考
:widths: 5, 20, 10
"項(xiàng)目一", "| 內(nèi)容一
| ?內(nèi)容一·point-1
| ?內(nèi)容一·point-2
| ?內(nèi)容一·point-3
| ?內(nèi)容一·point-4", ""
"項(xiàng)目二", "內(nèi)容二 ", ""
"項(xiàng)目三", "| 內(nèi)容一·第一行
| 內(nèi)容一·第二行", "參考一"
"項(xiàng)目四", "內(nèi)容一 :ref:`引用<ref-menu>` ", "參考二"
|
|
不完整表格實(shí)際效果
由于使用簡(jiǎn)體版桃焕，不支持ref的實(shí)際效果演示，所以會(huì)報(bào)錯(cuò)捧毛，但是在實(shí)際使用中沒(méi)有任何問(wèn)題
屬性
可以用css文件進(jìn)行樣式修改（待繼續(xù)研究）
.. table::
:class: XXXX
嵌入圖片
// 圖片可添加屬性如下（大圖片引用常見(jiàn)手法）
.. image:: funny.gif
:height: 100px
:width: 100px
:alt: funny cat picture
:align: center</pre>
:scale: 50%
// icon等小圖標(biāo)添加屬性如下（行內(nèi)可直接顯示观堂，附帶屬性看齊大圖片）
.. |Substitution Name| image:: path/filename.png
:width: 400
:alt: Alternative text
|Substitution Name| xxxxxx
多個(gè)圖片不連貫加入分隔
.. 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/>`_ 鏈接引入樣式
猜測(cè)結(jié)構(gòu)：`網(wǎng)站名字或者keyword<url>`_，其中下劃線為關(guān)門符號(hào)呀忧，必須有师痕，不然不生效，名稱跟url中間沒(méi)有空格
直接使用鏈接而账，則可以直接貼網(wǎng)站地址
- 百度 URI: https://www.baidu.com/
嵌入tip等
可以插入圖片胰坟、鏈接等等形式，注意引用格式即可
.. note::
`Tips的使用百度案例 <https://www.baidu.com/>`_ 同樣在url后需要有'_'福扬，才可以生效腕铸。
.. tip:: // 注釈
.. important::
.. caution:: // 注意
.. warning::
// 具體內(nèi)容與標(biāo)簽中間必須空一行，原先是英文表示铛碑，但是現(xiàn)在都是日文表示了（這里是因?yàn)楦鵀g覽器的默認(rèn)顯示語(yǔ)言）狠裹，意思還是一樣的
xxxxxx
已知的幾種引用圖示效果參考
// 文件引用（全文跳轉(zhuǎn)，相對(duì)url）
:doc:`../../page-management/create-page/index`
:doc:`title-name<name>`
// 部分引用（創(chuàng)造標(biāo)題內(nèi)容后跳轉(zhuǎn)）
:ref:`引用參考<ref-menu>`
// 被引用部分格式參考↓
.. _ref-menu:
===================
xxxxxx
===================
xxxxxx
導(dǎo)航跳轉(zhuǎn)
可以設(shè)定自定義對(duì)象汽烦，包含內(nèi)容后涛菠，用ref進(jìn)行跳轉(zhuǎn) :ref:對(duì)象名字<對(duì)象命名的內(nèi)容>，需要有關(guān)門部分
.. _edit-error-settings:
================================
導(dǎo)航跳轉(zhuǎn)案例一
================================
| 不重要的內(nèi)容…… :ref:`削除<delete-error-settings>` 不重要的內(nèi)容……
| 多個(gè)使用記得需要用空格與正文隔開(kāi) :ref:`作成<create-error-settings>` 引用部分在實(shí)際情況與url效果一般
| 只會(huì)顯示<>前的標(biāo)題文字內(nèi)容
可以包含多重結(jié)構(gòu)
================================
.. image:: images/edit-error-settings.png
:scale: 100
|
|
// ↑ 多個(gè)引用之間需要用關(guān)門分隔
.. _delete-error-settings:
================================
導(dǎo)航跳轉(zhuǎn)案例二
================================
在跳轉(zhuǎn)內(nèi)容中同時(shí)也可以引用其他，所以格式相同 :ref:`edit-error-settings` 確保自身對(duì)應(yīng)不出錯(cuò)
補(bǔ)充說(shuō)明
================================
可以不使用 `標(biāo)題<實(shí)際命名>` 的格式俗冻，直接寫鏈接也是可以的礁叔，如上↑
.. image:: images/delete-error-settings.png
:scale: 60
|
|
// 整塊內(nèi)容結(jié)束了一定要記得關(guān)門，是兩個(gè)丨迄薄，如↑
特殊符號(hào)
帶顏色的標(biāo)題寫法參考（_static/customized.css里寫css）：
實(shí)際效果參考
.. 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:`?`
其他細(xì)節(jié)
- 空格居中暫時(shí)用的是全角空格琅关，多空幾個(gè)才能看到效果
- 全角空格可以出段首縮進(jìn)效果，但是只有純文字才能奇效
- 所有命令段都需要回車來(lái)實(shí)現(xiàn)讥蔽，除了部分引入的內(nèi)容涣易，行元素的修飾符只會(huì)生效一個(gè)
- 轉(zhuǎn)義符“\”
- 可以通用簡(jiǎn)易css效果的，具體還需要研究冶伞，但是我是簡(jiǎn)體預(yù)覽版新症，案例不好做，待補(bǔ)充
- 為了效果好响禽，最好寫死圖片寬度徒爹，除了dialog、messagebox等特殊的大小
- table默認(rèn)stripe效果
- table-header默認(rèn)粗體
- 行內(nèi)圖片/icon引用感覺(jué)是以圖片本身大小為準(zhǔn)芋类，不太傾向標(biāo)準(zhǔn)行的大小
