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ù)文檔時(shí)Sphinx工具可將其轉(zhuǎn)為html、pdf、ePub等格式；更有者托管到GitHub中并導(dǎo)入readthedocs網(wǎng)站。 

 python安裝步驟

進(jìn)入python官網(wǎng)

下載安裝包

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

保持默認(rèn)Next

這里初學(xué)者默認(rèn)安裝路徑，方便后面用命令安裝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

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

 Sphinx安裝中

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

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目錄下可以看到生成的基本項(xiàng)目框架文檔

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

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

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

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

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

index.rst ：文檔項(xiàng)目的root目錄。多個(gè)文件時(shí)可用于連接其余文件。 

編寫 conf.py 和 index.rst 文件

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

:doc:命令屬于尋找目標(biāo)文件運(yùn)行 

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

 運(yùn)行命令 sphinx-build -b html source build 和 make html 生成 .html文件

 最終在build文件夾中生成.html文件，并可通過網(wǎng)頁查看

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

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

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

安裝完插件后用戶可以打開圖上這個(gè)窗口，進(jìn)行實(shí)時(shí)顯示當(dāng)前Rst格式的排版  

 Rst語法格式

其中空格要謹(jǐn)慎使用，其中空格運(yùn)用得當(dāng)能產(chǎn)生不一樣的效果反之則不符合語法標(biāo)準(zhǔn)報(bào)錯(cuò)

 標(biāo)題格式

 對(duì)應(yīng)顯示效果分別是一級(jí)標(biāo)題、二級(jí)標(biāo)題、三級(jí)標(biāo)題、四級(jí)標(biāo)題、五級(jí)標(biāo)題

超鏈接格式 

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

 圖片格式

  圖片目前使用有以下兩種方式：bd_logo1.png是引用網(wǎng)址、logo.png是引用當(dāng)前文件的相對(duì)路徑

 表格格式

//表格類型一
 
==== ====== ========== ==== == ===
編號(hào) 名稱   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!"

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

 標(biāo)注以及特殊提示符

 以下是顯示效果

代碼格式

需要代碼每行進(jìn)行縮進(jìn)一個(gè)空格

 顯示效果

RST格式文件編寫完成后需要重新進(jìn)入Windows命令窗\demo\test文件下

輸入 sphinx-build -b html source build 和 make html 命令生成新的 .html 文件

 以下是網(wǎng)頁中顯示效果

 總結(jié)

由此本文分享結(jié)束

Rst格式還有很多地方需要探究，Spinx工具亦是如此

到此這篇關(guān)于Sphinx環(huán)境配置及VScode編寫Rst文檔轉(zhuǎn)html的文章就介紹到這了,更多相關(guān)Sphinx環(huán)境配置內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！