Sphinx——Python生成API文档

1、简介

Sphinx是Python文档生成器,它基于reStructuredText标记语言,可自动根据项目生成HTML,PDF等格式的文档,无数著名项目的文档均用Sphinx生成,如机器学习库scikit-learn、交互式神器Jupyter Notebook

sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发。新版的Python3文档就是由sphinx生成的,并且它已成为Python项目首选的文档工具,同时它对C/C++项目也有很好的支持。更多详细特性请参考spinx官方文档,本篇博客主要介绍如何快速为你的Python注释生成API文档。

2、安装sphinx

pip install sphinx

3、生成api

  1. 新建项目sphinx_demo,src放项目代码,doc放sphinx自动生成的文件
    在这里插入图片描述

2.命令行进入doc目录cd doc
3.执行命令sphinx-quickstart,设置结构分离、项目名、作者名、版本号、语言(配置后面可修改)

Separate source and build directories (y/n) [n]: y
Project name: sphinx_demo
Author name(s): XerCis
Project release []: 1.0
Project language [en]: zh_CN 或 回车默认英文

在这里插入图片描述
4.在doc/source/conf.py指定项目代码路径

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

5.在doc/source/conf.py修改扩展extensions,添加功能【包括注释中的文档】、【支持NumPy和Google风格】、【包括测试片段】、【链接到其他项目的文档】、【TODO项】、【文档覆盖率统计】、【通过javascript呈现数学】

extensions = ['sphinx.ext.autodoc','sphinx.ext.napoleon','sphinx.ext.doctest','sphinx.ext.intersphinx','sphinx.ext.todo','sphinx.ext.coverage','sphinx.ext.mathjax',
]
  1. 在source/index.rst下新增如下内容
.. toctree:::maxdepth: 2:caption: Contents:

7.命令行进入doc目录,执行生成API文档命令sphinx-apidoc -o source …/src/
在这里插入图片描述
8.生成HTML
(linux环境执行命令):

make html 

windows环境需要执行命令

.\make html

4、重新生成

  1. 项目代码未变更

1 . 在doc下执行命令 make clean
2. 在doc下执行命令 make html(直接也行)

  1. 项目代码已变更

  2. 删除 doc/build 下的所有文件夹

  3. 删除 doc/source 下除index.rst的所有.rst文件

  4. 在doc下执行命令 sphinx-apidoc -o source …/src/

  5. 在doc下执行命令 make html

切换主题

安装主题 pip install sphinx_rtd_theme
修改 doc/source/conf.py 的 html_theme

html_theme = ‘sphinx_rtd_theme’
注释风格
reStructuredText(PyCharm默认)
NumPy
Google(官方推荐)

风格 特点 适用
reStructuredText 用冒号分隔 PyCharm默认
NumPy 用下划线分隔 倾向垂直,长而深的文档
Google 用缩进分隔 倾向水平,短而简单的文档
Sphinx对NumPy和Google风格的对比,英文不好可以参考中文版

extensions = [‘sphinx.ext.napoleon’]

设置PyCharm Docstrings风格
File→Settings→Tools→Python Integrated Tools

在PyCharm中Ctrl+Q可很方便查看注释

光标放在函数名左端Alt+Enter→Insert documentation string stub可快速插入注释文档

项目结构

doc:Sphinx文件
src:项目源代码
doc/build:Sphinx生成文件
doc/build/doctrees:doctree文件
doc/build/html:生成的HTML文件
doc/source:Sphinx配置文件
doc/source/conf.py:Sphinx用户自定义配置文件
doc/source/index.rst:首页结构
doc/source/test.rst:test模块结构
主题大全
Sphinx的主题默认为 alabaster

参考文档:
https://blog.csdn.net/lixiaomei0623/article/details/120530642
https://www.cnblogs.com/Terrypython/p/10203332.html

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

如若内容造成侵权/违法违规/事实不符,请联系长河编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

陪诊系统源码开发:实现个性化医疗陪护的创新之路

陪诊系统的源码开发在现代医疗中具有重要意义。本文将通过代码示例介绍陪诊系统的源码开发,展示如何实现个性化医疗陪护的创新方案。 1. 安装和环境设置: 首先,确保你的开发环境中已经安装了合适的编程语言和框架,比如Python和…

数据采集:selenium 获取 CDN 厂家各省市节点 IP

写在前面 工作需要遇到,简单整理理解不足小伙伴帮忙指正 对每个人而言,真正的职责只有一个:找到自我。然后在心中坚守其一生,全心全意,永不停息。所有其它的路都是不完整的,是人的逃避方式,是对…

基于XL32F003单片机的可控硅调光方案

可控硅调光是一种用于调节电源输出电压的技术,被广泛应用于各种场景。它主要通过改变波形的导通角度来调节输出电压的大小,从而实现对照明设备亮度的控制。在照明市场占据了很大的调光市场。 可控硅调光的兼容性强,应用范围广。例如&#xff…

fastgpt构建镜像

1.把client目录复制到服务器 .next和node_modules文件夹不用上传到服务器 在服务器目录运行 docker build -t fastgpt:1.0.3 . 构建服务 再运行 docker ps 就可以看到容器了

AKM10-58C大电流TVS二极管参数:58V 10000A

东沃(DOWO)AKM10-76C是什么二极管? 东沃生产AKM10-76C大电流TVS二极管吗?有现货吗? 除了AKM10-76C外,东沃(DOWO)生产的贴片大电流二极管还有哪些型号? …… AKM10-76C是厂…

怎样压缩mp4视频大小?

怎样压缩mp4视频大小?由于视频文件的体积通常比其他类型的文件更大,因此它们需要更多的存储空间来保存。但是,如果我们的设备、应用程序或平台不支持某些视频格式或分辨率,或者我们没有足够的存储空间来容纳这些大型视频文件&…

C语言易错点整理

前言: 本文涵盖了博主在平常写C语言题目时经常犯的一些错误,在这里帮大家整理出来,一些易错点会帮大家标识出来,希望大家看完这篇文章后有所得,引以为戒~ 一、 题目: 解答: 首先在这个程序中…

自己搭建Minecraft服务器并通过cpolar内网穿透实现与公网小伙伴联机我的世界

文章目录 1. Java环境搭建2.安装我的世界Minecraft服务3. 启动我的世界服务4.局域网测试连接我的世界服务器5. 安装cpolar内网穿透6. 创建隧道映射内网端口7. 测试公网远程联机8. 配置固定TCP端口地址8.1 保留一个固定tcp地址8.2 配置固定tcp地址 9. 使用固定公网地址远程联机 …

MIA文献阅读 —— 深度学习在医学图像分析中的最新进展及临床应用【2022】

目录 0 摘要1 引言2 深度学习方法概述2.1 监督式学习2.2 无监督学习2.2.1 自编码器 (Autoencoders)2.2.2 生成对抗网络(GANs)2.2.3 自监督学习 2.3. 半监督学习2.4 提高性能的策略2.4.1 注意力机制2.4.2 领域知识2.4.3 估计的不确定性 3 深度学习应用3.1 分类3.1.1 监督分类3.1…

免费清理电脑:删除垃圾文件以提升电脑性能

求助!电脑上没有可用空间 ​“我只在电脑上存储了大约100张照片,为什么我的硬盘空间已满?电脑运行速度也变得越来越慢,要疯了!现在我想安装更新的驱动程序。我可以释放磁盘空间吗?有免费的Windows电脑清…

免费开源使用的几款红黑网络流量工具,自动化的多功能网络侦查工具、超级关键词URL采集工具、Burpsuite被动扫描流量转发插件

免费开源使用的几款红黑网络流量工具,自动化的多功能网络侦查工具、超级关键词URL采集工具、Burpsuite被动扫描流量转发插件。 #################### 免责声明:工具本身并无好坏,希望大家以遵守《网络安全法》相关法律为前提来使用该工具&am…

【python】Leetcode(primer-set)

文章目录 78. 子集(集合的所有子集)90. 子集 II(集合的所有子集)792. 匹配子序列的单词数(判断是否为子集)500. 键盘行(集合的交集)409. 最长回文串(set) 更多…

Tomcat的安装与介绍

首先我们先了解一下什么是服务器?什么是服务器软件? 什么是服务器?安装了服务器软件的计算机。 什么是服务器软件? 服务器软件是一种运行在服务器操作系统上,用于接收和处理客户端请求,并提供相应服务和资…

微信小程序,封装身高体重选择器组件

wxml代码&#xff1a; // 微信小程序的插值语法不支持直接使用Math <wxs src"./ruler.wxs" module"math"></wxs> <view class"ruler-container"><scroll-view scroll-left"{{scrollLeft}}" enhanced"{{tru…

java八股文面试[java基础]——CGLIB动态代理与JDK动态代理

CGLIB CGLIB简介&#xff1a; 什么是CGLIB CGLIB是一个强大的、高性能的代码生成库。其被广泛应用于AOP框架&#xff08;Spring、dynaop&#xff09;中&#xff0c;用以提供方法拦截操作。Hibernate作为一个比较受欢迎的ORM框架&#xff0c;同样使用CGLIB来代理单端&#xff…

Kyligence Copilot 登陆海外,斩获 Product Hunt 日榜 TOP 2

8月14日&#xff0c;AI 数智助理 Kyligence Copilot 在全球知名科技产品平台 Product Hunt 上线&#xff0c;其以出色的产品创新实力&#xff0c;在激烈的竞争中脱颖而出&#xff0c;仅仅在 24 小时内收获了超过 400 个投票和近 200 条支持评论&#xff0c;荣登当日产品榜排名第…

PDF校对:追求文档的精准与完美

随着数字化时代的到来&#xff0c;PDF已经成为了多数机构和个人首选的文件格式&#xff0c;原因在于它的稳定性、跨平台特性以及统一的显示效果。但是&#xff0c;对于任何需要公开或正式发布的文档&#xff0c;确保其内容的准确性是至关重要的&#xff0c;这就是PDF校对显得尤…

智能化追踪与实时管理:RFID技术在流水线上的革命性应用

随着科技的不断发展&#xff0c;物联网技术已经深入到了我们生活的方方面面&#xff0c;其中&#xff0c;射频识别&#xff08;Radio Frequency Identification&#xff0c;简称RFID&#xff09;技术被广泛应用于各行各业。在流水线生产中&#xff0c;RFID技术的应用也越来越广…

Linux下的系统编程——makefile入门(四)

前言&#xff1a; 或许很多Winodws的程序员都不知道这个东西&#xff0c;因为那些Windows的IDE都为你做了这个工作&#xff0c;但我觉得要作一个好的和professional的程序员&#xff0c;makefile还是要懂。这就好像现在有这么多的HTML的编辑器&#xff0c;但如果你想成为一个专…

数据库怎么备份文件,数据库一般怎么备份

在当今的数字世界中&#xff0c;数据已经成为企业的生命线。无论是客户数据、业务数据还是内部流程&#xff0c;都需要通过数据库进行存储和管理。然而&#xff0c;数据的安全性和完整性也成为企业面临的一大挑战。在这种情况下&#xff0c;数据库备份尤为重要。那么&#xff0…