程序员经验分享-hwhale

sphinx+reStructuredText 文档写作

2023-05-16

文章目录

    • 1. 简介
      • spinx
      • reStructuredText (rst)
    • 写作环境配置
    • 参考文档

1. 简介

spinx

Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发. 新版的Python文档 就是由Sphinx生成的，
并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持. Sphinx还在继续开发. 下面列出了其良好特性,这些特性在Python官方文档中均有体现:

  • 丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual pages（man 文档）, 纯文本
  • 完备的交叉引用: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息
  • 明晰的分层结构: 可以轻松的定义文档树,并自动化链接同级/父级/下级文章
  • 美观的自动索引: 可自动生成美观的模块索引
  • 精确的语法高亮: 基于 Pygments 自动生成语法高亮
  • 开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API docs)等

reStructuredText (rst)

reStructuredText 是扩展名为.rst的纯文本文件，含义为"重新构建的文本"，也被简称为：RST或reST；是Python编程语言的Docutils项目的一部分，
Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。
Docutils 能够从Python程序中提取注释和信息，格式化成程序文档。

.rst 文件是轻量级标记语言的一种，被设计为容易阅读和编写的纯文本，并且可以借助Docutils这样的程序进行文档处理，

也可以转换为HTML或PDF等多种格式，或由Sphinx-Doc这样的程序转换为LaTex、man等更多格式

写作环境配置

安装sphinx

sudo pip install sphinx

安装 restructuredtext-lint

sudo pip install restructuredtext-lint

写作编辑器的安装与配置(vscode)

在vscode中安装 reStructuredText插件

参考文档

https://www.cnblogs.com/zhaojiedi1992/p/zhaojiedi_python_013_rst_spinx.html

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

sphinx

reStructuredText

文档写作

sphinx+reStructuredText 文档写作 的相关文章

  • reStructuredText 、Sphinx 资料汇总

    reStructuredText 用 reStructuredText 写作 xff1a 快速入门指南 reStructuredText rst 快速入门语法说明 reStructuredText rst 语法规则快速入门 在线 reStr

  • 重组文本列表出现“意外缩进”

    我没有成功使用 Restructedtext 获得简单的 3 级缩进列表 cat test rst Title aaaa aaaa2 aaaa2 aaaa3 aaaa aaaa Ok rst2html test rst gt tmp a h

  • 如何增加 Sphinx / 重构文本中的固定宽度字体大小？

    我正在使用 Sphinx 生成使用重构文本作为标记的文档 但是 当我使用一些内联格式使文本以固定宽度字体显示时 no cache渲染的 HTML 以较小的字体显示文本 如何增加 Sphinx reStructured Text 中的固定宽度

  • reStructuredText 的 ANTLR 语法（规则优先级）

    第一个问题流 大家好 这可能是这个问题的后续 Antlr 规则优先级 我正在尝试为以下内容编写 ANTLR 语法重构文本标记语言 我面临的主要问题是 如何在不掩盖其他语法规则的情况下匹配任何字符序列 常规文本 让我们以带有内联标记的段落为例

  • Sphinx：对不同的输出格式使用不同的指令

    假设您有一个 reStructuredText 文档 并希望使用 Sphinx 2 x 将其导出为两种格式 HTML 和 PDF 您想在这两种格式中放入一些略有不同的内容 例如 文本 我是HTML 出现在 HTML 版本中 而 我是PDF

  • Sphinx 内联包括

    我想使用 include 函数内联 但只有当我用两行新行与前面的文本分开时 我才能让它实际包含我想要的文件 在有人问之前 我想包含的文件是一个协议号 所以不 它根本不会从新行中受益 我希望能够轻松更改它 以便我可以在文档的多个位置使用它 我

  • sphinx 构建时出现重复索引警告；如何包含文件而不对其内容建立索引？

    我希望创建一个single html rst包含我所有的文件class method attribute etc 还可以将分类符号拆分到单独的页面中 e g single html rst single html include foo r

  • 在 Sphinx 中生成外部链接

    我想链接到 Sphinx 文档中的某个 URL a href http some url blah a 我在文档中发现了类似的内容 http sphinx doc org ext extlinks html http sphinx doc

  • Python Sphinx 锚点在任意线上

    如何使用 Sphinx 在 ReST 中的任意行设置锚点引用 为了更清楚 这里有一个例子 A title with an anchor some stuff 这将创建一个标题A title with an anchor并添加一个额外的on

  • RestructedText 文件中可能存在文本的私有部分吗？

    我正在将公司的一些文档从 md 转换为 rst 以便在 ReadTheDocs com 中显示 其中一些文档中的内部部分不适合我们的客户使用 有没有办法标记这些部分 以便 Sphinx 不会将其呈现为 HTML Use the ifconf

  • 是否可以在重构文本中以两栏样式书写？

    我想使用重组文本写一篇研究论文 是否可以采用此类文档固有的两栏样式 我看了看规格 http docutils sourceforge net docs ref rst restructuredtext html但除了使用桌子这将是一个真正的

  • 可以使用“ifconfig”块（reStructuredText）有条件地定义目标

    是否可以有条件地定义target https docutils sourceforge io docs ref rst restructuredtext html hyperlink targets在 reStructuredText 文件

  • 在 MySQL 和 Python 中以可重复的方式处理 1970 年之前的日期

    在我的 MySQL 数据库中 我的日期可以追溯到 1700 年代中期 我需要以某种方式将其转换为类似于 Unix 时间的格式的整数 int 的值并不重要 只要我可以从数据库或用户输入中获取日期并生成相同的 int 即可 我需要使用 MySQ

  • 为具有特定标题的通用狮身人面像警告定义标记

    我正在使用 Sphinx 为 Python 程序生成 HTML 文档 我想使用generic admonition http docutils sourceforge net docs ref rst directives html gen

  • 将可点击的 SVG 图像插入 Sphinx 文档

    我有 SVG 图像文件 其中有多个节点 每个节点都与 URL 关联 如果我直接在浏览器中打开此文件 我可以单击每个节点 它将打开不同的 URL 但是 当我在 Sphinx 文档中使用这张图片时 它不起作用 图片作为一个整体呈现 所以我需要通

  • Sphinx 文档中使用全局变量标准化链接

    我正在使用 Sphinx 来记录工作项目 我想在整个文档的多个页面上使用指向下载的相同链接 例如 home rst Hi I want you to download my project download blah com downloa

  • 如何将单个部分中的 Sphinx 章节分成不同的文件？

    我正在使用出色的 Sphinx 工具来创建一些文档 并且我试图通过将同一部分的章节分成单独的文件来保持代码库的模块化形式 请参阅此处了解 章节 和 部分 的定义 http www sphinx doc org en stable rest

  • Sphinx内联代码高亮

    我使用 Sphinx 制作一个包含代码示例的网站 我成功地使用了 code block获取语 法高亮的指令 但我无法使用此代码获得内联语法突出显示 role bash code language bash Test inline bash

  • 变量替换在 Sphinx 中无法正常工作

    我有一个用以下内容制作的文档项目Sphinx http www sphinx doc org en stable 我通过配置键使用全局变量rst epilog My conf py文件包含以下内容 rst epilog MY VERSION

  • RestructedText 文档中的行距不一致

    我正在为我公司的文档构建 RST 文件 一件令人恼火的事情是 枚举列表在行距方面似乎没有任何一致性 有没有简单的方法来解决这个问题 Robert 这是一个众所周知的问题docutils Sphinx 构建的库 来自 GitHub 上的 Sp

随机推荐

  • KITTI数据集下载链接

    1 简介 KITTI数据集由德国卡尔斯鲁厄理工学院和丰田美国技术研究院联合创办 xff0c 是目前国际上最大的自动驾驶场景下的计算机视觉算法评测数据集 该数据集用于评测立体图像 stereo xff0c 光流 optical flow xf

  • python ftp下载上传文件或文件夹

    目录 1 包引用 2 函数说明 2 1 连接登录 2 2 常规操作指令 xff08 对标linux指令 xff09 2 3 上传文件 2 4 下载文件 2 5 退出 实际需要 xff0c 编写一个脚本 xff0c 通过ftp下载文件或这文件

  • C++ fstream/ifstream/ofstream文件读写操作

    文章目录 写在前面1 fstream类的成员函数 open xff0c close open读写操作 2 fstream子类 ofstream ifstreamofstream 向文件中写数据ifstream 从文件中读数据 写在前面 在C

  • yolov3 完整讲解-从数据编码角度介绍

    对yolo系列文章的发展做个总结 神经网络训练模型的根本就是真值与预测值比较 xff0c 落实到不同任务最根本的区别的就是对真值的编码 理解深度学习的关键是明白真实值如何编码 xff0c 下面从这个角度介绍 1 问题的引入 深度学习最早用来

  • 小样本学习

    机器学习就是从数据中学习 xff0c 从而使完成任务的表现越来越好 小样本学习 是具有有限监督数据的机器学习 类似的 xff0c 其他的机器学习定义也都是在机器学习定义的基础上加上不同的限制条件衍生出来 例如 xff0c 弱监督学习 是强调

  • cmakelist.txt 编译并引用动态库

    示例代码 hello slam xff1a 1 简单的 exe 使用 CMakeLists txt 设置工程以 debug 形式编译 helloSLAM cpp 内容 xff1a include lt iostream gt using n

  • 红外相机工作原理

    1 红外热摄像机特点 自然界所有温度在绝对零度 273 以上的物体都会发出红外线 xff0c 红外线 或称热辐射 是自然界中存在最为广泛的辐射 大气 烟云等吸收可见光和近红外线 xff0c 但是对3 5微米和8 14微米的红外线却是透明的

  • linux 关闭socket shutdown,关于socket的关闭：close和shutdown

    声明 该博文以socket中 关闭输出流为例进行说明 为了方便讲解 我们把DataOutputstream dout 61 new DataOutputStream new BufferedOutputStream mySocket get

  • 纯css打造漂亮的html表格,table CSS制作好看的网页表格

    幸运的是html规范提供了许多无素和属性来提高数据表格对于这些设备的可访问性 1 summary 和 caption 第一元素是表格的caption 它基本上用做表格的标题 尽管这不是必须有的元素 但是尽可以使用caption总是好的 另一

  • mavlink协议详解_MAVLink学习之路05_ MAVLink应用编程接口分析

    描述 MAVLink应用编程主要内容 2 1 发送和接收说明 利用MAVLink通信协议进行编程 xff0c 主要实现的功能就是 xff1a 1 发送端 将需要发送的数据 如 xff1a SysState BatVol xff0c 添加MA

  • tf-faster-rcnn跑demo.py出现InvalidArgumentError (see above for traceback): Assign requires shapes of bo

    基于tf faster rcnn做图像识别时 xff0c 使用自己的数据集 训练过程没有问题 xff0c 然后跑demo的时候报 xff1a InvalidArgumentError see above for traceback Assi

  • tortoise git linux,TortoiseGit 使用入门

    首先要确定TortoiseGit已找到msysgit 如果先安装msysgit 再装TortoiseGit 一般TortoiseGit 就会自动的识别 设置与查询的方法 这里从开始菜单进入设置 这是TortoiseGit的设置界面 xff0

  • java听课笔记2（数组）

    4 Java数组的定义 问题 xff1a 一个班有50个人 xff0c 如何在程序中输出所有同学的学号 xff1f 数组的定义 xff1a 一组能够存储相同数据类型的变量的集合 数组一定要有长度 数组中每个数据称为元素 xff0c 数组元素

  • 嵌入式linux和plc,嵌入式、单片机、PLC哪个的发展前景更可观

    前言 xff1a 嵌入式标准定义 用于控制 监视或者辅助操作机器和设备的装置 嵌入式定义很广泛 xff0c 广泛到单片机 PLC FPGA 43 CPLD ARM 43 Linux实际上都属于嵌入式范畴 各个方向薪资水平 嵌入式 ARM 4

  • stm32正常运行流程图_stm32初始化流程图解析

    STM32系列基于专为要求高性能 低成本 低功耗的嵌入式应用专门设计的ARM Cortex M3内核 stm32参数 xff1a 12V 36V供电 兼容5V的I O管脚 优异的安全时钟模式 带唤醒功能的低功耗模式 内部RC振荡器 内嵌复位

  • anaconda必须安装在c盘吗_windows安装Anaconda3

    本教程教大家在windows10里面安装Anaconda3 xff0c 过程简单 xff0c 无论实在windows7还是windows10 xff0c 安装过程一致 下载Anaconda3 进入Anaconda官网 xff0c 点击右上角

  • java libraries在哪_java.library.path在哪？

    编译运行可得 Code publicclassHelloWorld publicstaticvoidmain String args System out println 34 Hello World 34 System out print

  • 海盐高级中学2021高考成绩查询,出来啦！海盐的高考状元是她！海盐高考成绩、普高录取结果出炉！...

    原标题 xff1a 出来啦 xff01 海盐的高考状元是她 xff01 海盐高考成绩 普高录取结果出炉 xff01 重磅消息 xff01 2018年嘉兴高考分数出炉 很多家长都知道网络消息比官网来得快 xff0c 几天前就有家长来问九哥了

  • 计算机c盘中哪些东西能删除吗,C盘哪些文件可以删除

    电脑C盘容量越来越小了 xff0c 尤其是比较老的电脑 xff0c 由于硬盘容量比较小 xff0c 所以C盘容量比较小 xff0c 当C盘文件过多电脑桌面由下脚经常会弹出 您的C盘系统资源不足 C盘是系统盘 xff0c 垃圾文件过多或者剩余

  • sphinx+reStructuredText 文档写作

    文章目录 1 简介spinxreStructuredText rst 写作环境配置参考文档 1 简介 spinx Sphinx 是一种文档工具 xff0c 它可以令人轻松的撰写出清晰且优美的文档 由 Georg Brandl 在BSD 许可

热门标签