【Python】Sphinx 文档生成器

news2024/11/13 15:45:05

目录

1. Sphinx 介绍

2. Sphinx 实战

2.1. 初始化 Sphinx 工程

2.2. 编译项目

2.3. Sphinx 主题

2.4. 增加 Sphinx 文档


1. Sphinx 介绍

Sphinx是一个Python文档生成器,它基于reStructuredText标记语言,可自动根据项目生成HTML,PDF等格式的文档。Sphinx可以令人轻松的撰写出清晰且优美的文档,除了天然支持Python项目以外,Sphinx对C/C++项目也有很好的支持,并在不断增加对其它开发语言的支持 。

如果您需要编写技术文档,可以用reStructuredText或Markdown格式编辑文件,然后使用Sphinx工具转换成html、PDF、ePub等格式,或者托管到GitHub并导入ReadtheDocs网站 。

2. Sphinx 实战

2.1. 初始化 Sphinx 工程

  • 创建项目目录
mkdir sphinx-doc
cd sphinx-doc
  • 初始化命令
sphinx-quickstart
  • 命令输出结果

  • 项目文件结构
│  make.bat
│  Makefile
├─build
└─source
    │  conf.py
    │  index.rst
    ├─_static
    └─_templates

2.2. 编译项目

  • 编译为本地文件
make html

build 目录下生成如下文件

│  make.bat
│  Makefile
├─build
│  ├─doctrees
│  │      environment.pickle
│  │      index.doctree
│  └─html
│      │  .buildinfo
│      │  genindex.html
│      │  index.html  # 这个文件可直接用浏览器打开
│      │  objects.inv
│      │  search.html
│      │  searchindex.js
│      │
│      ├─_sources
│      │      index.rst.txt
│      │
│      └─_static
│              alabaster.css
│              basic.css
│              custom.css
│              doctools.js
│              documentation_options.js
│              file.png
│              jquery-3.5.1.js
│              jquery.js
│              language_data.js
│              minus.png
│              plus.png
│              pygments.css
│              searchtools.js
│              translations.js
│              underscore-1.13.1.js
│              underscore.js
└─source
    │  conf.py
    │  index.rst
    ├─_static
    └─_templates

用浏览器打开 build\html\index.rst 可以看到

  • 编译为 HTTP 服务

make html 的编译方式需要打开 html 文件才能查看,使用如下命令则可以使用 HTTP 服务的形式来查看。

sphinx-autobuild source build/html

命令执行结果为

 可以通过 http://127.0.0.1:8000/ 查看。

2.3. Sphinx 主题

Sphinx 模型主题是 alabaster,可以通过 https://sphinx-themes.org/ 查看 sphinx 更多的主题。

 接下来切换一个比较明显的主题 groundwork-sphinx-theme,打开 source/conf.py 做如下修改

# html_theme = 'alabaster'
html_theme = 'groundwork'

2.4. 增加 Sphinx 文档

  • 新的项目文件结构如下
│  make.bat
│  Makefile
└─source
    │  conf.py
    │  index.rst
    ├─_static
    ├─_templates
    └─文章
        │  index.rst
        ├─第一章
        │      index.rst
        └─第二章
                index.rst

预览结果如下:

3. 项目源码

https://gitee.com/hl0929/sphinx-doc.git

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.coloradmin.cn/o/714340.html

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈,一经查实,立即删除!

相关文章

使用 OpenCV 进行按位运算和图像屏蔽

在本教程中,我们将了解如何使用按位运算 AND、OR、XOR 和 NOT。 图像处理中使用按位运算从图像中提取感兴趣区域 (ROI)。 正如您所看到的,两个矩形重叠的区域已被删除(黑色),因为在该区域中两个像素都大于 0。 按位非<

浅析代谢组学最常用到的数据分析方法 图形详解pca pls-da opls-da

代谢组学是一门对某一生物或细胞所有低分子质量代谢产物&#xff08;以相对分子质量<1000的有机和无机的代谢物为研究核心区&#xff09;进行分析的新兴学科。生物样本通过NMR、GC-MS、LC-MS等高通量仪器分析检测后&#xff0c;能产生大量的数据&#xff0c;这些数据具有高维…

网页版在线流程图绘制工具Diagram

网页地址&#xff1a;Diagram 可以将流程图保存为图片、网址等多种格式。 界面&#xff1a;

【PortAudio】PortAudio 音频处理库Demo

1. 介绍 PortAudio是一个免费、跨平台、开源的音频I/O库。看到I/O可能就想到了文件&#xff0c;但是PortAudio操作的I/O不是文件&#xff0c;而是音频设备。它能够简化C/C的音频程序的设计实现&#xff0c;能够运行在Windows、Macintosh OS X和UNIX之上&#xff08;Linux的各种…

SAP从入门到放弃系列之生产车间相关单据打印

文章目录概览 一、前言二、系统相关设置2.1、配置:1&#xff1a;2.2、配置点2&#xff1a;2.3、配置点3 三、主数据准备四、测试场景准备五、小结 一、前言 通常在项目实施的时候&#xff0c;如果没有MES&#xff0c;那么生产调度相关岗位下达订单后&#xff08;订单下达感觉没…

K8s部署微服务(springboot+vue)

文章目录 前言一、使用到的K8s资源1.1 Deployment1.2 Service 二、Springboot基础服务部署2.1 网关gateway2.2 鉴权auth2.3 文件file2.4 流程flow2.5 消息message2.6 组织org2.7 系统通用system2.8 用户user2.9 Node 三、Vue前端部署3.1 项目前端nginx3.2 静态资源服务nginx 四…

迪杰斯特拉算法(求最短路径)

迪杰斯特拉算法&#xff08;求最短路径&#xff09; 迪杰斯特拉算法用于查找图中某个顶点到其它所有顶点的最短路径&#xff0c;该算法既适用于无向加权图&#xff0c;也适用于有向加权图。 注意&#xff0c;使用迪杰斯特拉算法查找最短路径时&#xff0c;必须保证图中所有边…

相对位置编码(二) Relative Positional Encodings - Transformer-XL

1. Motivation 在Transformer-XL中&#xff0c;由于设计了segments&#xff0c;如果仍采用transformer模型中的绝对位置编码的话&#xff0c;将不能区分处不同segments内同样相对位置的词的先后顺序。 比如对于segmenti&#xfffd;&#xfffd;&#xfffd;&#xfffd;&…

pycharm安装opencv-python报错

问题一 通过pycharm中的Terminal窗口安装opencv-python错误如下&#xff1a; 上图所示为部分错误&#xff0c;全部错误如下&#xff1a; Building wheel for opencv-contrib-python (PEP 517) ... errorERROR: Complete output from command D:\anzhuanglujing\Anaconda\python…

从零开始之PID控制

从零开始系列之PID控制&#xff0c;宗旨就是以说人话的方式讲述它&#xff0c;真正的做到从零开始&#xff0c;小白一看就会&#xff0c;一学就废。 一、什么是PID控制&#xff1f; PID控制&#xff08;比例-积分-微分控制&#xff09;由比例单元&#xff08;Proportional&…

玩耍的猫咪【 InsCode Stable Diffusion 美图活动一期】

1️⃣ 工具介绍 InsCode是一个集成了在线IDE、在线AI编程、在线算力租赁、在线项目部署以及在线SD 模型使用的综合代码开发平台。 Stable Diffusion是目前最火的AI绘画工具之一&#xff0c;它是一个免费开源的项目。通过Stable Diffusion&#xff0c;可以很轻松的通过文字描述…

上半年结束,下半年继续冲!

前言: 这周直播也把雷神写的Ffmpeg推流器讲解完了&#xff0c;而一同时&#xff0c;一转眼间&#xff0c;2023年已经过半&#xff0c;正式进入了下半年&#xff1a; 因为上半年已经开始在做解析Ffmpeg 最新版本的源码&#xff0c;所以下半年&#xff0c;我会继续坚持讲解Ffmpeg…

“GPT+健康医疗”赋能医疗行业“数智化”发展,景联文科技提供高质量医疗数据库

近日&#xff0c;ChatGPT这个代表着通用版的大型语言模型以其出色的表现在全球互联网上引人注目。它所使用的GPT技术基础为人工智能应用开启了全新的世界。 “大模型时代已经到来。它已变成基础设施&#xff0c;变成算力&#xff0c;变成生产力。大模型可能有通用技术&#xf…

C++杂谈-友元和操作符重载

1、友元- friend 我的理解&#xff1a;通过设置友元函数和友元类来让外部函数来访问私有成员&#xff0c;这样虽然破坏了类的封装型和隐藏性&#xff0c;但是提高了程序的运行效率&#xff08;减少了某些安全性检查的过程&#xff09;。 友元函数和友元类统称友元&#xff0c;…

Nginx+Tomcat(多实例)实现动静分离和负载均衡(四层、七层)

目录 一、Tomcat 多实例部署 二、反向代理的两种类型 三、NginxTomcat实现负载均衡和动静分离&#xff08;七层代理&#xff09; 1.动静分离和负载均衡原理 2.实现方法 3.部署实例 &#xff08;1&#xff09;部署Nginx负载均衡服务器 &#xff08;2&#xff09;配置Tom…

C++之GNU C的__attribute__常用属性(一百五十)

简介&#xff1a; CSDN博客专家&#xff0c;专注Android/Linux系统&#xff0c;分享多mic语音方案、音视频、编解码等技术&#xff0c;与大家一起成长&#xff01; 优质专栏&#xff1a;Audio工程师进阶系列【原创干货持续更新中……】&#x1f680; 人生格言&#xff1a; 人生…

使用 ZBrush、Ornatrix 和 Substance 3D Painter 重现哈利波特中的凤凰

今天瑞云渲染小编给大家带来了Ramn Tapia 分享 Phoenix 项目背后的工作流程&#xff0c;解释了如何在 Ornatrix 中完成修饰&#xff0c;并展示了纹理化过程。 介绍 你好&#xff0c;有创造力的读者朋友们 我的名字是Ramn&#xff0c;但在数字艺术领域&#xff0c;我的名字是ra…

【 Android11 无线热点开发 】无线AP开与关、无线AP信息获取

前言 前面四篇文章介绍完了有线网络、无线网络的开发过程&#xff0c;下面介绍下Android 11上网络的终结篇&#xff0c;无线热点的开发流程。 相关文章 1、【 Android11 WiFi开发 一 】WiFi列表获取与展示 2、【 Android11 WiFi开发 二 】WiFi连接、断开 3、【 Android11 Wi…

软件为什么要进行故障演练?主要为了什么?

随着现代社会的高度信息化和软件的广泛应用&#xff0c;软件的质量和可靠性对于保障用户体验和信息安全显得尤为重要。为了保证软件的稳定运行和即时响应&#xff0c;软件故障演练成为软件开发和运维过程中的重要环节&#xff0c;那软件为什么要进行故障演练&#xff1f;主要为…

IIC(I2C)协议

I2C&#xff08;Inter-Integrated Circuit&#xff09;:是一种串行通信协议&#xff0c;用于在集成电路之间进行数据传输。它由飞利浦公司开发&#xff0c;并广泛应用在各种电子设备和传感器之间进行通信。 I2C通信协议由两根线组成&#xff1a; 一个是用于数据传输的串行数据线…