程序员经验分享-hwhale

Windows下配置sphinx+reStructuredText详解

2023-05-16

Windows下配置sphinx+reStructuredText详解
最近有朋友想在windows下做个人笔记，没有找到顺手的工具，问我有什么好的工具推荐。正好前两天在网上看到一款做文档的利器sphinx+reStructText，当时在ubuntu下搭了下环境试了试，做笔记真的非常方便。今天在windows下试了试，遇到一些问题，但总算成功了，现整理如下。

简介

1 reStructuredText是什么？
reStructuredText是扩展名为.rst的纯文本文件，含义为”重新构建的文本“，是python编程语言的Docutils项目的一部分。.rst文件是一种轻量级标记语言，与html的复杂结构相比，它的设计对人更加友好，被设计为容易阅读和编写的纯文本，并且可以借助Docutils这样的程序进行文档处理，也可以转换为html或pdf等多种格式，或由Sphinx这样的程序转换为man手册等更多格式

2 sphinx是什么？
Sphinx 是一种工具，它允许开发人员以纯文本格式编写文档，以便采用满足不同需求的格式轻松生成输出。它使用 reStructuredText标记语法来提供文档控制，可以将 Sphinx想像成为一种文档框架：它会抽象化比较单调的部分，并提供自动函数来解决一些常见问题，比如突出显示标题索引和特殊代码（在显示代码示例时），以及突出显示适当的语法

环境搭建

1 搭建Python环境
sphinx和reStructuredText是python编程语言的一部分，所以需要先配置好Python环境。
在Python的官方网站下载安装程序按默认选项安装即可，默认安装路径C:\python37
需要注意的是根据你的主机是32位还是64位来选择下载哪个进行安装

2 安装setuptools
setuptools是python的一个增强工具，我们安装模块式常用的easy_install命令就是setuptools中的一个工具；
去官方网站下载ez_setup.py，如下图所示，右击->目标另存为，将ez_setup.py下载到本地

然后将ez_setup.py放到python的安装目录C:\python37，如下图所示
在这里插入图片描述

进入dos窗口，执行以下命令安装setuptools
cd C:\python37
C:\python37\python.exe ez_setup.py

在这里插入图片描述

3 安装sphinx
安装完setuptools，我们就是可以只用其中的easy_install命令很简单的安装sphinx模块
进入dos界面，输入以下命令
C:\python37\easy_install.exe sphinx
在这里插入图片描述

4 设置环境变量
设置环境变量的作用是让你在输入命令的时候不需要在输入完整的路径，只要输入命令名称即可。
在桌面右击计算机->属性->高级系统设置->环境变量，选择系统变量的path项点击编辑，增加以下两个路径
;C:\python37;C:\python37\scripts

在这里插入图片描述
需要注意的是每个路径都是以英文的分号来分割，我们添加了两个路径，在这两个路径之间需要用“;”分开，另外，在第一个路径之前也需要增加一个“;”，与原有的路径进行区分

到此为止，windows下搭建sphinx+reStructuredText的工作就全部完成了。
下一节我们以一个简单的实例来展示它的强大功能

使用实例

首先在桌面建立一个空文件夹sphinx-test，在dos下进入该目录，执行以下命令
cd C:\Users\xlzh\Desktop\sphinx-test
sphinx-quickstart

在这里插入图片描述

运行该命令会提示很多是选项，我们只需要在project Name后写上自己的工程名称，Authors Name后写上作者名称，其他的按默认即可
命令结束后会在sphinx-test目录下生成以下几个文件

在这里插入图片描述

我们要编辑的就是其中的index.rst，首先我们先不着急编辑，先看一下默认的效果
进入dos窗口，进入shpinx-test目录，执行以下命令
cd C:\Users\xlzh\Desktop\sphinx-test
make.bat html
在这里插入图片描述

出现上面的效果说明转换html通过，会在该目录_build目录下生成响应的html文件，我们进入目录下的_build/html，使用浏览器打开index.html，查看页面效果

在这里插入图片描述

以上显示是默认的页面，现在让我们回过头来用记事本打开index.rst并进行编辑，增加几行代码，展示自己的东西，如下所示
在这里插入图片描述

需要注意的是此时的index.rst是ANSI编码的，不支持汉字，需要点击文件->另存为，保存为utf-8格式，覆盖原文件即可
修改完毕，再次运行命令
make.bat html

刷新刚才的页面看下效果吧

在这里插入图片描述

OK，剩下的工作就是好好学习reStructuredText语言，然后不断的make.bat html和查看页面进行调试了，注意rst文件编写如果不符合规则，make.bat的时候会提示报错信息，按照报错信息修改对应文件的对应行即可

推荐学习网站：

http://jwch.sdut.edu.cn/book/rst.html

这个是reStructuredText的简明教程，这个网站本身也是reStructuredText编写的，我们可以通过点击页面左侧的show source查看右侧窗口的源码，比对源码与页面显示，学习更有效率

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

Windows

sphinx

reStructuredText

Windows下配置sphinx+reStructuredText详解 的相关文章

  • 批量设置命令的输出和错误以分隔变量

    在Windows 7批处理 cmd exe命令行 中 我试图将命令的标准输出 stdout 和标准错误 stderr 重定向到单独的变量 因此第一个变量设置为输出 第二个变量设置为输出 变量设置为错误 如果有 而不使用任何临时文件 我已经尝

  • 如何在 PowerShell 中比较本地文件与 FTP 服务器上的文件的年龄并下载远程复制是否较新

    我正在编写一个 PowerShell 脚本 以帮助我为工作设置新电脑 希望这不仅仅是我一个人会使用 所以我正在尝试考虑所有事情 我在 FTP 服务器上保存了离线安装程序 java flash reader 等 如果本地副本尚未保存在创建的

  • 在 powershell 脚本中以不同用户身份本地运行代码块

    这是非常简单的事情 但我就是无法让任何东西发挥作用 我想在特定用户下的 powershell 脚本中运行块代码 关键字是locally我正在使用 powershell 2 0 Invoke Command 似乎需要远程主机 我运行以下命令

  • Windows 上的 Node.js 和 Express

    今晚 我决定尝试在我的 Windows 7 计算机上使用 Express 构建一个简单的 Node js 应用程序 安装过程还算顺利 但 Express 拒绝配合 以下是我已采取的步骤 使用以下位置提供的 MSI 安装 Node jshtt

  • 每个进程每个线程的时间量

    我有一个关于 Windows 和 Linux 中进程和线程的时间量子的问题 我知道操作系统通常为每个线程提供固定的时间量 我知道时间量根据前台或后台线程而变化 也可能根据进程的优先级而变化 每个进程有固定的时间量吗 例如 如果操作系统为每个

  • 64 位大型 malloc

    malloc 失败的原因是什么 尤其是在 64 位中 我的具体问题是尝试在 64 位系统上分配一大块 10GB RAM 该机器有 12GB RAM 和 32GB 交换空间 是的 malloc 是极端的 但是为什么它会成为一个问题呢 这是在带

  • 在 WSL Ubuntu 20.04 上安装 npm 后，我收到消息“/usr/bin/env: ‘bash\r’: No such file or directory”

    运行时我看到以下消息npm install or npm来自终端的命令 执行中node按预期工作 gt npm install usr bin env bash r No such file or directory 2023 年 7 月更

  • Node.js + Socket.io + Windows 7 / 8？

    我一直在到处寻找 但似乎找不到解决方案 是否可以在 Windows 7 上的 Node js 上安装 Socket io 如果没有 是否有某种替代方案 或者您知道未来有任何 Windows 支持吗 通常使用 Node js 包管理器 但是我

  • 在 C# 中使用反射列出枚举中的值

    我正在尝试使用反射来列出一个 Visual Studio 解决方案内的各个项目中的一些类的公共成员和方法 我尝试访问的所有类都是 C 的 并且它们都是从 C 类访问的 我用来进行这些调用的代码如下 public void PopulateE

  • Windows平台下C语言控制串口DTR和RTS引脚

    如何在windows平台上控制串口的DTR和RTS引脚 我希望通过升高或降低电压来对其进行位敲击或操作 您需要使用EscapeComm 函数 https learn microsoft com en us windows desktop a

  • 为 Windows 98 编译 Qt

    我需要支持 Windows 98 Qt 文档声称这是可能的 但没有说明 Qt 4 6 的分布式二进制文件不能在 Win98 上运行 而且我采样的大多数 Qt 应用程序也不能在 Win98 上运行 对于几个确实在 98 上运行的应用程序 我询

  • fprintf() 线程安全吗？

    我正在为野人就餐问题的某些变量编写一个 C 解决方案 现在 我创建线程 每个线程都将 FILE 获取到同一个调试文件 在线程内我正在使用 fprintf 进行一些打印 打印的语句不受任何类型的互斥锁等保护 我没有在调试文件中观察到任何交错行

  • Pip 无法在 Windows 上安装 Twisted

    我正在尝试在 Windows 8 计算机上安装 Twisted 在 Twisted 官方网站上 只有一个 Windows 版的 Wheel 文件 https twistedmatrix com trac wiki Downloads htt

  • 无法启动 Windows 服务，错误 1064

    我编写了一个在 Win10 上运行的 Windows 服务 它运行得非常好 直到我决定对其进行一些更改 我重写了一些逻辑 在调试和发布配置中进行了测试 一切都很好 然后 我使用卸载了当前版本的服务installutil exe u serv

  • Jenkins 可以检测到任何 svn 用户每次提交代码吗？

    Jenkins 可以检测到任何 svn 用户每次提交代码吗 我想知道每次 Jenkins 提交 svn user 时 有什么方法或 jenkins 插件吗 现在我用svn updateJenkins 中的 cmd 来更新 svn 您可以按照

  • 为什么 fopen 无法打开已存在的文件？

    我在 Windows XP 上使用 Visual Studio 6 是的 我知道它很旧 构建 维护 C DLL 我遇到了 fopen 无法打开现有文件的问题 它总是返回 NULL 我试过了 通过将 errno 和 doserrno 设置为零

  • C# WMI 在远程 PC 上运行一个 exe，然后在同一台 PC 上运行另一个 exe，然后在网络路径上调用 Directory.CreateDirectory 并失败

    使用 C WMI 我在另一台计算机上启动一个 exe 该 exe 使用 C 启动另一个 exeProcess班级 最后一个 exe 尝试调用Directory CreateDirectory使用网络路径 又名 comp1 d dir Dir

  • Windows批处理文件：将结构转换为单行字符串

    我需要将这个艰巨的任务作为批处理文件来完成 这对于 C 来说不是最困难的 但在 DOS 中是一个地狱 至少对我来说 我需要将结构转换为单个 var 字符串 才能在我的程序中再次将它们转换为该结构 别担心回归 一切都已经完成了 该结构的大小会

  • 可以读取目标文件吗？

    我很好奇 obj文件 我几乎不知道它们是什么 或者它们包含什么 所以我用 Vim 文本编辑器打开它们 我在里面发现了一种类似外星人的语言 有什么办法可以理解它们代表什么以及它们的内容是什么 另外 它们的用途是什么 Thanks Sure 但

  • 在高 dpi Windows 平台上自动重新缩放应用程序？

    我正在编写一个需要在高 dpi Windows 192dpi 而不是 96dpi 上运行的 Qt 应用程序 不幸的是 Qt 框架尚不支持高 dpi 至少在 Windows 上 因此我的应用程序及其所有元素看起来只有应有尺寸的一半 有没有办法

随机推荐

  • 关于FreeRTOS的系统时钟节拍

    不管是什么系统 xff0c 运行都需要有个系统时钟节拍 xTickCount就是FreeRTOS的系统时钟节拍器 在每个滴答定时器中断中xTickCount 43 1 xff0c 比如stm32中 xff0c 具体是在delay c中的vo

  • python基础：for循环和while循环区别和相同点，range函数介绍

    循环语句可以让计算机重复和自动的执行代码 xff0c 减少人的工作量 文章目录 for循环while循环两种循环对比 for循环 格式 for in 循环语句 xff0c 简称for循环 xff1b 先看下它的格式吧 span class

  • 不忘初心•砥砺前行——江苏叁拾柒号仓智能科技有限公司2019年中总结会

    2019年7月20日上午 xff0c 江苏叁拾柒号仓智能科技有限公司 下称37号仓 2019年中总结会在集团1楼多媒体厅隆重举行 xff0c 37号仓执行董事魏标 xff0c 总经理卞石磊 xff0c 子雨集团党支部书记 工会主席徐伟 xf

  • python基础：布尔运算和四个语句

    布尔运算 计算机的逻辑判断 xff0c 只有True 判断为真 和alse 判断为假 两种结果 xff0c 计算真假的过程就叫做布尔运算 xff0c True和False就是布尔值 while和if中的布尔运算 相同点 xff1a 在whi

  • 解读编码和文件读写

    解读编码和文件读写 编码的本质就是让只认识0和1的计算机 xff0c 能够理解我们人类使用的语言符号 xff0c 并且将数据转换为二进制进行存储和传输 这种从人类语言到计算机语言转换的形式 xff0c 就叫做编码表 xff0c 它让人类语言

  • BeautifulSoup库的简单使用

    BeautifulSoup是什么 网页解析库BeautifulSoup xff0c 用来解析和提取网页中的数据 安装BeautifulSoup库 BeautifulSoup库目前已经进阶到第4版 xff08 Beautiful Soup 4

  • 运行地面站详细步骤

    第一步 xff1a 打开bin目录 xff0c 保留Backup DLL文件夹 xff0c 删除除Backup DLL文件夹之外的所有文件 xff1b 第二步 xff1a 打开Backup DLL文件夹 xff0c 复制里面所有的dll 粘

  • 关于qt和js的html一些修改

    1 调试打印js文件 maptype tms html 文件 xff0c 没有qdebug 和printf 可以用 xff0c 但可以用alert 来代替 xff0c 用alert 地图上会出现对应窗口显示 xff0c 来判断程序 逻辑 2

  • qt+directshow usb摄像头及音频设备录制视频

    最近来了个项目 xff0c 有一块功能是usb摄像头录制视频并且录音的实现 xff0c 网上的东西七七八八什么技术都有 xff0c 先用opencv打了半天环境不能录音频 xff0c 后来用ffmpeg xff0c 原谅我太菜 xff0c

  • VSCode中Git解决冲突的步骤

    VSCode中Git解决冲突的步骤 1 gt gt 合并分支后 如果存在冲突 右下角会出现一个提示框 提示 存在合并冲突 请在提交之前解决这些冲突 2 gt gt 左边导航第三个图标中 xff0c 找到产生冲突的文件 3 gt gt 打开文

  • VsCode一定要安装的几个插件

    1 Vetur VUE语法高亮 智能感知 Emmet等 xff0c 包含格式化功能 xff0c Alt 43 Shift 43 F xff08 格式化全文 xff09 xff0c Ctrl 43 K Ctrl 43 F xff08 格式化选

  • ccm-slam环境配置

    ccm slam 配置过程记录 介绍 xff1a 一种协同视觉slam方法 传统的slam是一个机器人完成定位与建图的任务 xff0c 但对于大范围的环境 xff0c 多机器人协同建图往往能提高效率 xff0c ccm slam就是基于这个

  • 从大到小排序，Comparator类型

    import java util Arrays import java util Comparator public class Main public static void main String args 注意 xff0c 要想改变默

  • 11种服务器编程语言对比（附游戏服务器框架） 2020.06

    各语言对比 语言版本TIOBE排名垃圾回收类型系统性能Web后端非Web后端特性Java142是中Python3 83是动态低C 43 43 174高不适合Node js147 是动态低PHP7 48是动态低不适合Go1 1412是中Rub

  • 【stm32定时器配置步骤和相关概念解析——LL库】

    系列文章目录 文章目录 系列文章目录前言一 cubeMX定时器介绍二 通用寄存器三 PWM模式四 LL库 PWM模式 xff08 定时器14为例 xff09 1 结构体说明2 LL库代码 前言 一 cubeMX定时器介绍 Slave Mod

  • 华为MateBook&暗影精灵游戏本恢复出厂设置

    总目录 文章目录 总目录前言一 华为MateBook恢复出厂设置1 接上电源2 重启 开机按F10 二 暗影精灵游戏本恢复出厂设置1 接上电源2 重启 开机按F11 前言 记一次个人华为笔记本和暗影精灵游戏本的恢复操作 xff0c 说不准下

  • C/C++类库大全（附github连接）

    C 43 43 资源大全中文版 浏览中发现一篇总结的很全的c c 43 43 类库 xff0c 在此做记录 xff0c 以备不时之需 github地址 xff08 内有各个库的源码连接 xff09 https github com jobb

  • VScode 中 Clangd 使用

    1 VScode 中 Clangd 使用 VScode 中 Clangd 优缺点 优点 占用系统资源确实比 C C 43 43 少了很多 xff0c 无论是 CPU 还是 内存的使用 xff08 最重要 xff09 缺点 操作相较于 C C

  • FreeRTOS 线程安全的printf输出（使用STM32F103）

    https blog csdn net baidu 23187363 article details 53811144 环境 STM32F103开发板 HAL库 xff08 标准库也没事换个串口输出函数就行 xff09 MDK5 28 ST

  • Windows下配置sphinx+reStructuredText详解

    Windows下配置sphinx 43 reStructuredText详解 最近有朋友想在windows下做个人笔记 xff0c 没有找到顺手的工具 xff0c 问我有什么好的工具推荐 正好前两天在网上看到一款做文档的利器sphinx 4

热门标签