Sphinx環境設定及VScode編寫Rst檔案轉html的步驟

2023-03-21 06:01:19

Sphinx環境設定

安裝python3
通過python3安裝sphinx

sphinx官方網站：Installing Sphinx — Sphinx documentation

python官方網站：Welcome to Python.org

sphinx主要用於編寫 reStructuredText 和 Markdown 格式技術檔案，

編寫此類技術檔案時Sphinx工具可將其轉為html、pdf、ePub等格式；更有者託管到GitHub中並匯入readthedocs網站。

python安裝步驟

進入python官網

下載安裝包

開啟exe檔案，勾選設定到系統環境變數並選擇自定義安裝

保持預設Next

這裡初學者預設安裝路徑，方便後面用命令安裝sphinx

安裝完成介面

win+R開啟命令窗輸入python，確定是否安裝成功和安裝版本是否為python3

Sphinx安裝步驟

Windows命令窗輸入以下命令，安裝Sphinx軟體包

國內最好用華清源安裝，使用-i指定安裝源

py -3 -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx

安裝中可能會出現pip版本過低安裝不了Sphinx，需執行命令更新pip再安裝Spinx

Sphinx安裝中

安裝完成，在Windows命令框順序輸入每一行命令建立demotest資料夾試執行

mekdir demo //建立demo資料夾
cd demo     //開啟demo資料夾
mekdir test //建立test子資料夾
cd test     //開啟test子資料夾

Windows命令框輸入以下命令開啟Sphinx工具設定基本引數

sphinx-quickstart

這些設定引數都可以在之後的conf.py檔案中開啟重新更改

設定完成後在Windows目錄下可以看到生成的基本專案框架檔案

build：存放最終生成的檔案如html、pdf、ePub

source：存放Rst格式等檔案以及圖片資料

Makefile：批次處理指令，使用make命令時用來構建檔案輸出

設定完後在source檔案中會出現 index.rst 和 conf.py 兩個檔案；使用者可根據需求編寫這兩個檔案達到自己的效果

conf.py : 一個pythom檔案，用於存放Sphinx的設定引數

index.rst ：檔案專案的root目錄。多個檔案時可用於連線其餘檔案。

編寫 conf.py 和 index.rst 檔案

Introduction
============
This is the introduction of documentation
 
API
===
:doc:'Run API</demo_test>'

:doc:命令屬於尋找目標檔案執行

import os
import sys
sys.path.insert(0,os.path.abspath('../..'))

執行命令 sphinx-build -b html source build 和 make html 生成 .html檔案

最終在build資料夾中生成.html檔案，並可通過網頁檢視

上圖是相當於是通過 Rst 轉換 html 的預設框圖，內容排版都可自定義

VScode編寫Rst格式檔案 VScode環境設定下載外掛 reStructuredtext 和 RST Preview（可以實時顯示效果變化）

source資料夾中建立 .rst 格式檔案使用VScode開啟

安裝完外掛後用戶可以開啟圖上這個視窗，進行實時顯示當前Rst格式的排版

Rst語法格式

其中空格要謹慎使用，其中空格運用得當能產生不一樣的效果反之則不符合語法標準報錯

標題格式

對應顯示效果分別是一級標題、二級標題、三級標題、四級標題、五級標題

超連結格式

超連結目前使用的有以下兩種方式：Sphinx官網是先宣告後參照、Python官網是直接參照

圖片格式

圖片目前使用有以下兩種方式：bd_logo1.png是參照網址、logo.png是參照當前檔案的相對路徑

表格格式

//表格型別一
 
==== ====== ========== ==== == ===
編號 名稱   NAND FLASH eMMC SD USB
==== ====== ========== ==== == ===
1    MODE0  0          0    0  1
2    MODE1  1          1    1  0
3    CFG1-4 1          0    0  X
4    CFG1-5 0          1    0  X
5    CFG1-6 0          1    1  X
6    CFG1-7 1          0    0  X
7    CFG2-3 0          1    0  X
8    CFG2-5 0          0    1  X
==== ====== ========== ==== == ===
 
//表格型別二
 
+------------+------------+-----------+ 
| Header 1   | Header 2   | Header 3  | 
+============+============+===========+ 
| body row 1 | column 2   | column 3  | 
+------------+------------+-----------+ 
| body row 2 | Cells may span columns.| 
+------------+------------+-----------+ 
| body row 3 | Cells may  | - Cells   | 
+------------+ span rows. | - contain | 
| body row 4 |            | - blocks. | 
+------------+------------+-----------+
 
//表格型別三
 
.. csv-table:: Frozen Delights!
  :header: "Treat", "Quantity", "Description"
  :widths: 15, 10, 30
 
 
  "Albatross", 2.99, "On a stick!"
  "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
  crunchy, now would it?"
  "Gannet Ripple", 1.99, "On a stick!"

表格目前使用有以下三種方式：