程序员经验分享-hwhale

Sphinx环境配置以及VScode编写Rst文档转html

2023-05-16

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命令框顺序输入每一行命令创建\demo\test文件夹试运行
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!"

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

  •  标注以及特殊提示符

​​​​​​​

 以下是显示效果

  • 代码格式

需要代码每行进行缩进一个空格

 显示效果

RST格式文件编写完成后需要重新进入Windows命令窗\demo\test文件下

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

 

 以下是网页中显示效果

 总结

由此本文分享结束

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

本文内容由网友自发贡献，版权归原作者所有，本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容，请联系:hwhale#tublm.com(使用前将#替换为@)

Sphinx环境配置以及VScode编写Rst文档转html 的相关文章

随机推荐

  • USB转串口芯片CH340系列及CH340模块使用方法（CH340驱动，接线，串口下载详细介绍）

    USB 转串口芯片 CH340 我们为什么要用到CH340驱动呢 xff1f CH340驱动就是USB转串口的驱动的一种 xff0c 因为我们现在的电脑上 xff0c 已经不存在串口 xff0c 所以我们一般使用USB转串口芯片 xff0c

  • prusa2.6.0 树形支撑(有机支撑)Organic体验测试 3d打印及下载失败解决

    目前官网没有这个2 6版本 xff0c 只有2 5 2下载 xff0c 是没有树形支撑的 如果试用2 6版本 xff0c 需要从GitHub下载 地址为 xff1a https github com prusa3d PrusaSlicer

  • 无人机在户外无GPS环境下用什么导航方法问答

    无人机在户外无GPS环境下用什么导航方法 xff1f 无人机在户外无GPS环境下可以使用多种导航方法 xff0c 包括 xff1a 1 视觉导航 xff1a 利用摄像头检测地面特征实现导航 2 磁场感应导航 xff1a 利用永磁体和地球磁场

  • 网络中的图片传输

    前言 一张图片经过网络从主机 A 传输到主机 B xff0c 主机 B 在收到这张图片后将其保存在本地 xff0c 对应步骤为 xff1a 读 xff1a 主机 A 读取待传输的图片数据传 xff1a 主机 A 通过 Socket 将图片传

  • 一道有趣的C语言题：int *p=(int *)((int)a+1)；

    偶然间看到这样一个c语言题目 xff1a 小端模式 int main void int a 5 61 1 2 3 4 5 int p 61 int int a 43 1 xff1b printf 34 X r n 34 p return 0

  • 一、FREERTOS学习之 freertos移植流程步骤

    目录 一 FREERTOS资源包下载 二 移植 1 资源包整理 三 工程添加 1 添加 2 编译路径添加 3 修改FreeRTOSConfig h 4 修改stm32f10x it c 5 注意 一 FREERTOS资源包下载 官网 xff

  • 三、FreeRTOS学习之 freertos的任务创建

    目录 一 任务创建 xff1a 1 静态创建 xff1a 2 动态创建 xff1a 3 任务句柄 4 例 xff1a 一 任务创建 xff1a 在freertos中 xff0c 提供了两种创建任务的方式 xff1a 静态创建 xff0c 动

  • 七、FreeRTOS学习之 软件定时器

    一 基本概念 在freertos中 xff0c 软件定时器的功能跟单片机中使用的定时器差不多 xff0c 通过设置一段时间 xff0c 等到时间到达 xff0c 定时器进入中断 xff0c 执行相应的功能函数 xff0c 被调用的函数叫做定

  • 软件iic 的编写与调试

    一 了解 1 硬件iic 其对应的芯片上有iic外设 xff0c iic的引脚是固定的 xff0c 硬件iic是直接配置内部的寄存器 xff0c 只要配置好寄存器 xff0c 外设就会产生标准的协议时序 xff0c 只需要直接调用控制函数

  • 运算符重载（），[]

    include lt iostream gt include lt cstring gt using namespace std class yunsuan private int a b c int len num char name 3

  • vector

    include lt iostream gt include lt vector gt include lt algorithm gt using namespace std 容器 xff1a vector 相当于一个数组 迭代器 xff1

  • STM32外设之TIM定时器使用及输出比较模式PWM生成，PWM频率和占空比计算，文末有固件库TIM驱动文件的函数讲解

    TIM 定时器是stm32单片机中的一个外设 xff0c STM32有8个定时器 xff0c 分别是2个高级定时器TIM1TIM8 xff0c 4个通用定时器TIM2 5 2个基本定时器TIM67 根据不同型号的单片机 xff0c 挂载的定

  • Java多线程之~~~~使用wait和notify实现生产者消费者模型

    在多线程开发中 xff0c 最经典的一个模型就是生产者消费者模型 xff0c 他们有一个缓冲区 xff0c 缓冲区有最大限制 xff0c 当缓冲区满 的时候 xff0c 生产者是不能将产品放入到缓冲区里面的 xff0c 当然 xff0c 当

  • 拷贝、移动构造

    include lt iostream gt using namespace std class temp private char a public temp char c char b a 61 new char 2 a 0 61 c

  • Dockerfile

    Dockerfile Dockerfile简介1 Dockerfile基本介绍2 Dockerfile构建过程3 Dockerfile指令用法 Dockerfile构建镜像1 Dockerfile使用CentOS构建apache镜像1 1相

  • MySQL数据库备份与恢复

    在项目的开发过程中数据库的备份是非常重要的 xff0c 为了防止数据库受到破坏 xff0c 造成不可估量的损失 xff0c 所以一定要进行数据库的备份 xff0c 并且需要掌握数据库恢复方法 xff0c 在发生数据库损坏的时候 xff0c

  • Linux设备驱动基础知识

    一 认识驱动 1 什么是驱动 不知道的情况下 xff0c 我们一般会去问度娘 xff0c 但是度娘的这个回答比较专业化 xff0c 对小白来说并不容易理解 xff0c 依旧不明白驱动到底是个啥 度娘 xff1a 驱动 xff0c 计算机软件

  • 接口及实现方法

    什么是接口 接口 xff08 英文 xff1a Interface xff09 xff0c 在JAVA编程语言中是一个抽象类型 xff0c 是抽象方法的集合 xff08 接口中的所有的方法都是抽象方法 xff09 xff0c 接口通常以in

  • JS中Document对象

    Document对象 Document对象就是一个标记性文档对象 它就是HTML文件本身 当浏览器把一个html文件加载到内存中之后 xff0c 在内存中就会形成这个document对象 document URL xff1a 返回当前页面的

  • Sphinx环境配置以及VScode编写Rst文档转html

    Sphinx环境配置 安装python3通过python3安装sphinx sphinx官方网站 xff1a Installing Sphinx Sphinx documentation python官方网站 xff1a Welcome t

热门标签