使用sphinx快速生成Python API 文档

Python 工具库每日推荐 【Sphinx】 在 conf.py 中设置自定义主题# 更多选项...这个例子使用了流行的 Read the Docs 主题,并自定义了一些选项。Sphinx 作为一个强大而灵活的文档生成工具,为 Python 开发者提供了创建高质量文档的完美解决方案。通过本文的介绍和示例,我们看到了 Sphinx 在文档创建、API 参考生成、多格式输出等方面的卓越表现。从简单的项目文档到复杂的技术手册,Sphinx 都能够高效地完成任务。 阅读详情

不管是开源还是闭源,文档都是很重要的。当然理论上说,最好的文档就是代码本身,但是要让所有人都能读懂你的代码这太难了。所以我们要写文档。大部分情况,我们不希望维护一份代码再加上一份文档,这样做很容易造成文档和代码的不一致,程序员最讨厌更新文档了。所以最佳实践就是在程序员代码中加注释,然后通过构建脚本自通生成文档。

对应于Pyhon,有很多可供选择的工具:

  • sphinx 中文版介绍 Sphinx使用 reStructuredText作为标记语言(类似Markdown),可扩展,功能强大。要注意的是何有一个开源的搜索也叫Sphinx,斯芬克斯果然太受欢迎,开源的世界起个名字不容易呀。

  • pdoc 是一个简单易用的命令行工具,可以生成Python的API文档

  • Doxygen 是老牌的文档生成工具,可以针对各种语言生成文档,我们以前在C++的项目中曾经使用过

  • 其他还有诸如 pydoc , pydoctor 等等

下面我就介绍一下如果使用Sphinx为你的python项目快速的构建API 文档。

首先要安装Sphinx,不同的操作系统有不同的安装方式,Sphinx的源代码在这里 , 你也可以自己构建。我推荐使用pip install。(注,如果你安装了Anaconda,Sphinx已经包含在内了)

然后,假定你的python的源代码是在 src 目录下,我们在同一级并行建立一个文档目录 doc (你当然可以根据自己的项目需要,确定目录命名和结构)。

在doc目录下运行 

sphinx-quickstart

sphinx会提示你的项目的一些设置,生成项目的配置文件,这里给出一些推荐的配置:

> Root path for the documentation [.]:
<ENTER>
> Separate source and build directories (y/N) [n]:
y
> Name prefix for templates and static dir [_]:
<ENTER>
> Project name:
an_example_pypi_project
> Author name(s):
Andrew Carter
> Project version:
0.0.1
> Project release [0.0.1]:
<ENTER>
> Source file suffix [.rst]:
<ENTER>
> Name of your master document (without suffix) [index]:
<ENTER>
> autodoc: automatically insert docstrings from modules (y/N) [n]:
y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:
n
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
y
> todo: write “todo” entries that can be shown or hidden on build (y/N) [n]:
n
> coverage: checks for documentation coverage (y/N) [n]:
n
> pngmath: include math, rendered as PNG images (y/N) [n]:
n
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:
n
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:
y
> Create Makefile? (Y/n) [y]:
n
> Create Windows command file? (Y/n) [y]:
n

运行完毕,sphinx会生成项目的配置文档conf.py还有源文件(后缀为rst)

下一步要为捏python源文件生成sphinx的源文件,用来生成API文档,需要运行

sphinx-apidoc [options] -o outputdir packagedir [pathnames]

其中outputdir是doc目录,packagedir是src目录,也就是你的python代码包所在的目录

运行好后,会对每一个Python包生成一个rst文件,你可以编辑该文件来修改生成文档的细节,一般情况下不用改。

好了,准备工作做好了以后,就可以生成API文档了。在运行文档生成脚本之前,要确保你的Python源代码所在的包在系统路径中是可以找到的,需要修改conf.py。因为在生成文档是需要运行你的python代码,要保证code运行不出错。

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

在doc目录下运行脚本

sphinx-build -b html . ./ouput

在output目录会生成HTML格式的API文档。(也可以选其他文档格式)

Sphinx还有一个automsummay的扩展,可能能简化以上的过程,等我试一试在更新结果。


《遥感大模型生产级实战:从数据到决策的端到端AI工程》系列第一部分:AI遥感工程师的基础设施与工具链-文章 4:传统遥感分析与机器学习基线 本章将系统性地介绍经典遥感分析工作流,从数据预处理到多维度特征工程,再到如何利用经典的机器学习模型(如随机森林、支持向量机)进行监督与非监督学习。我们将通过一个完整的“智慧农业作物分类”项目实战,展示如何利用我们之前构建的数据湖和工具链,从原始数据到最终的分析结果,构建一个性能可靠、可解释性强的基线系统。更重要的是,我们将深入剖析这种传统方法的局限性,从而为后续章节引入遥感大模型的必要性提供强有力的论证。 阅读详情

相关推荐

夜间灯光遥感数据介绍及下载汇总

夜间灯光遥感数据介绍及下载汇总

qq_43874102的博客 1万+

使用sphinx生成python项目的api文档(html格式的api文档)

sphinx官方文档:https://zh-sphinx-doc.readthedocs.io/en/latest/intro.html sphinx需要安装:sudo pip3 install sphinx sphinx的使用: 1、创建目录: mkdir pro/doc/doc_file -p mkdir pro/mypro -p cd pro/mypro ...

YPFeime的博客 3554

野火STM32F407(骄阳)+无刷直流驱动板+永磁同步电机控制学习记录(四)(基于HAL库)

以上内容都是参考别人资料自学的,很多地方都是凭感觉,因为理论部分不太会算,只要电机能转就行,其他性能指标都没考虑,因为不会,所以这纯属是学习记录帖。带宽在500时,电流波动小,但是响应很慢,就是堵转后不太容易恢复转动。速度环带宽设定小了,响应不够快,带宽设定大了波动比较大,电机感觉起来也震一点,而且,当带宽设到200的时候,启动直接就锁死了,应该是PI增益设定太大了。电流环带宽的试验:去掉速度环,让Iq_Set=2,Ud=0,此时电机是电流环闭环控制,用手堵转电机然后松开,看电流的波动以及响应情况。

XUEXIDEXIAOhai的博客 4555

使用sphinx自动建立API文档(一)

1、使用 demo 的 python 文件 建立test_demo为根目录,下面分别建立doc和src文件夹。 doc:之后用来存储生成的 html 文件和相关配置 src:源 python 文件 src下面的 demo 文件分别有如下内容: demo1: class Demo1(): &quot;&quot;&quot; English Demo1. &quot;&quot;&quot; def dem..

longgb123的博客 1136

AI工程化之生成式UI & A2UI(一)

本文系统介绍了生成式UI和Google A2UI技术。生成式UI通过AI直接生成前端代码(完全生成式)或DSL(混合式),实现千人千面的动态界面和研发提效。Google A2UI提出组件级和消息级协议,采用JSON规范实现渲染框架解耦,支持多端渲染。文章详细阐述了A2UI的架构设计,包括协议生成、服务端处理和渲染器实现,并对比了与传统前端框架的差异,指出A2UI本质是UI=F(AI(UI)+AI(state))的创新模式。最后通过playground项目展示了A2UI的实践应用。

qq_34306228的博客 593

iOS开发者必备:从越狱设备里提取IPA的三种方法(含Filza、iTools实战)

本文详细介绍了iOS开发者从越狱设备提取IPA文件的三种实用方法,包括使用Filza文件管理器、AFC2配合桌面工具以及命令行高级技术。内容涵盖环境准备、操作步骤和技术原理,帮助开发者高效获取应用包文件,适用于逆向工程、测试分析等场景。

weixin_28717969的博客 827

使用sphinx快速为你python注释生成API(html)文档

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

weixin_42618420的博客 2080

手把手教你学simulink(95.1)--PID控制实例:基于Simulink的PID控制温度控制系统建模与仿真

温度控制是工业自动化、家用电器、医疗设备以及航空航天等领域中常见的控制问题。通过精确的温度控制,可以提高生产效率、降低能耗并确保产品质量。PID(比例-积分-微分)控制器因其结构简单、性能稳定且易于实现而被广泛应用于各种温度控制系统。本项目旨在通过MATLAB/Simulink平台设计和验证一个基于PID控制的温度控制系统,重点研究PID参数调优方法、系统动态响应特性以及稳态误差消除能力。

MHD0815的博客 794

使用sphinx自动生成python项目说明文档

使用sphinx自动生成项目说明文档

freeline的博客 3449

构建基于知识图谱的金融风险关联网络

在金融领域,风险的识别和管理至关重要。传统的风险分析方法往往只能处理单一维度的数据,难以全面捕捉金融市场中复杂的风险关联关系。构建基于知识图谱的金融风险关联网络的目的在于整合多源异构的金融数据,通过知识图谱的方式清晰地展示金融实体之间的复杂关系,从而更准确地识别潜在的金融风险,为金融机构的风险管理决策提供有力支持。本项目的范围涵盖了从金融数据的收集、预处理,到知识图谱的构建,再到金融风险关联网络的搭建和分析。

SuperAGI2025 1421

osgEarth加载大疆数据

【代码】osgEarth加载大疆数据。

weixin_44769745的博客 308

使用sphinx快速为你python注释生成API文档

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

gaoyan0335的专栏 833

scottplot5中使用signalXY图,如何更新数据?

🏆本文收录于《优快云问答解答》专栏,主要记录项目实战过程中的Bug之前因后果及提供真实有效的解决方案,希望能够助你一臂之力,帮你早日登顶实现财富自由🚀;同时,欢迎大家关注&&收藏&&订阅!持续更新中,up!up!up!!

**My Coding Family** 2449

python生成api文档_sphinx快速生成Python API文档

Python有个自带的工具可以生成Python的项目文档叫pydoc,但是我觉得最好用的还是Python-Sphinx,这里我们就讲一下python-Sphinx的使用。Sphinx可以自动获取代码中的(''' ''' 注释),自动生成文档。先看看最后要成为的效果,先提起你的兴趣安装Sphinxpip install Sphinx写个我们需要生成文档的项目-代码建一个测试项目code, 下面有两个...

weixin_39610594的博客 341

蓝牙模块HM-10手册

蓝牙模块HM-10手册,该手册对蓝牙模块HM-10进行了详细的介绍和使用方法以及一些AT指令。

RU DOS版、EFI版32bit/64bit BIOS常用工具

DOS版、EFI版的RU工具,可用来查看IO、MEM、PCI、SMBIOS等资源。亲测在EFI SHELL下可用。

Sphinx——自动生成Python文档

Sphinx是一个可自动生成python项目api的工具,使用起来也比较简单,只需要在项目上进行简单的配置,即可生成项目的api文档 简介 Sphinx是Python文档生成器,它基于reStructuredText标记语言,可自动根据项目生成HTML,PDF等格式的文档,无数著名项目的文档均用Sphinx生成,如机器学习库scikit-learn、交互式神器Jupyter Notebook sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl

lixiaomei0623的专栏 1万+

假人有限元模型

假人模型,车辆碰撞假人有限元模型,适合做乘员安全的研究者利用

Python API 文档自动生成(Sphinx、MkDocs、Swagger)的实现方式

综上所述,Sphinx、MkDocs 和 Swagger 各有千秋,适用于不同的场景。如果你的项目需要详细的多格式文档输出,Sphinx 是最佳选择;如果偏好简洁直观的 Markdown 编写方式,MkDocs 更加合适;而对于需要对外提供 API 接口的项目,Swagger 的交互式特性无疑是最吸引人的。无论选择哪种工具,重要的是保持文档的一致性和及时更新,这样才能真正发挥文档的价值。```

2501_91230491的博客 1252

最新的sdio 4.0 spec 协议标准 带书签 高清完整PDF版

Part-E1-SDIO-Specification-Ver4.00-Final-120220.pdf:最新的sdio 4.0 spec 协议标准 带书签 高清完整PDF版,包括SDIO 接口的外设,SDIO 接口官方协议等。

Sphinx AutoAPI 使用教程

Sphinx AutoAPI 使用教程 项目介绍 Sphinx AutoAPI 是一个用于生成完整 API 文档的 Sphinx 扩展。与传统的 Sphinx autodoc 不同,AutoAPI 不需要加载、运行或导入正在记录的项目,而是通过解析源代码来生成文档。这使得文档生成过程更加自动化,减少了手动编写文档的工作量。 项目快速启动 安装 首先,通过 pip 安装 Sphinx AutoAPI...

gitblog_00048的博客 518

sphinx-apidoc

一、使用 二、选项 三、automodapi 一、使用 sphinx-apidoc [OPTIONS] -o &lt;OUTPUT_PATH&gt; &lt;MODULE_PATH&gt; [EXCLUDE_PATTERN, …] sphinx-apidoc是一个自动生成Sphinx源的工具,使用该autodoc扩展。 MODULE_PATH:是 python 的源...

longgb123的博客 1629
上一篇: Python 并行分布式框架之 Celery
下一篇: 用HTML5构建一个流程图绘制工具
刚是程序员
博客等级 码龄9年 47粉丝 41原创
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值