快捷導(dǎo)航

Sphinx環(huán)境配置及VScode編寫Rst文檔轉(zhuǎn)html的步驟

更新時間：2023年03月20日 11:15:36 作者：JunFN8

sphinx主要用于編寫 reStructuredText 和 Markdown 格式技術(shù)文檔，編寫此類技術(shù)文檔時Sphinx工具可將其轉(zhuǎn)為html、pdf、ePub等格式，這篇文章主要介紹了Sphinx環(huán)境配置及VScode編寫Rst文檔轉(zhuǎn)html,需要的朋友可以參考下

Sphinx環(huán)境配置

安裝python3
通過python3安裝sphinx

sphinx官方網(wǎng)站：Installing Sphinx — Sphinx documentation??????

python官方網(wǎng)站：Welcome to Python.org

sphinx主要用于編寫 reStructuredText 和 Markdown 格式技術(shù)文檔，

編寫此類技術(shù)文檔時Sphinx工具可將其轉(zhuǎn)為html、pdf、ePub等格式；更有者托管到GitHub中并導(dǎo)入readthedocs網(wǎng)站。

python安裝步驟

進入python官網(wǎng)

下載安裝包

打開exe文件，勾選配置到系統(tǒng)環(huán)境變量并選擇自定義安裝

保持默認Next

這里初學(xué)者默認安裝路徑，方便后面用命令安裝sphinx

安裝完成界面

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

Sphinx安裝步驟

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

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

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

安裝中可能會出現(xiàn)pip版本過低安裝不了Sphinx，需運行命令更新pip再安裝Spinx

Sphinx安裝中

安裝完成，在Windows命令框順序輸入每一行命令創(chuàng)建\demo\test文件夾試運行

mekdir demo //創(chuàng)建demo文件夾
cd demo     //打開demo文件夾
mekdir test //創(chuàng)建test子文件夾
cd test     //打開test子文件夾

Windows命令框輸入以下命令打開Sphinx工具配置基本參數(shù)

sphinx-quickstart

這些配置參數(shù)都可以在之后的conf.py文件中打開重新更改

配置完成后在Windows目錄下可以看到生成的基本項目框架文檔

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

source：存放Rst格式等文件以及圖片數(shù)據(jù)

Makefile：批處理指令，使用make命令時用來構(gòu)建文檔輸出

配置完后在source文件中會出現(xiàn) index.rst 和 conf.py 兩個文件；用戶可根據(jù)需求編寫這兩個文檔達到自己的效果

conf.py : 一個pythom文件，用于存放Sphinx的配置參數(shù)

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文件，并可通過網(wǎng)頁查看

上圖是相當于是通過 Rst 轉(zhuǎn)換 html 的默認框圖，內(nèi)容排版都可自定義

VScode編寫Rst格式文件 VScode環(huán)境配置下載插件 reStructuredtext 和 RST Preview（可以實時顯示效果變化）

source文件夾中創(chuàng)建 .rst 格式文件使用VScode打開

安裝完插件后用戶可以打開圖上這個窗口，進行實時顯示當前Rst格式的排版

Rst語法格式

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

標題格式

對應(yīng)顯示效果分別是一級標題、二級標題、三級標題、四級標題、五級標題

超鏈接格式

超鏈接目前使用的有以下兩種方式：Sphinx官網(wǎng)是先聲明后引用、Python官網(wǎng)是直接引用

圖片格式

圖片目前使用有以下兩種方式：bd_logo1.png是引用網(wǎng)址、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!"

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