数据分析数据科学数据处理【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址https://gitcode.com/gh_mirrors/pa/pandas点击查看免费下载doc/sphinxext是 pandas 文档构建体系中存放自定义 Sphinx 扩展的专用目录其中包含announce.py与contributors.py两个工具前者从 git 历史与 GitHub 数据生成发布公告所需的贡献者/PR 名单后者以 Sphinx 指令形式把名单自动渲染进whatsnew发布说明页面。本文以该目录的 README.rst 为脉络结合两个扩展的完整实现、文档配置与 90 余个发布说明中的实际调用系统讲解 pandas 如何自动化维护贡献者致谢这一发布流程环节读者可据此理解并复用到自己的 Sphinx 文档项目中。一、目录定位pandas 文档体系中的自定义扩展层pandas 文档 使用 Sphinx 构建官方 README.rst 对doc/sphinxext目录的定位只有一句话This directory contains custom sphinx extensions in use in the pandas documentation.即该目录专用于存放 pandas 文档自身开发、而非来自第三方生态的 Sphinx 扩展。目前目录下只有两个文件announce.py命令行脚本用于生成发布公告中的贡献者与 PR 名单输出 UTF-8 编码的 reStructuredTextcontributors.py真正的 Sphinx 扩展注册contributors指令将名单渲染进whatsnew各版本页面。两个文件的分工是计算与渲染的分离contributors.py通过from announce import build_components见 contributors.py直接复用announce.py中的名单计算逻辑二者共享同一套 git 分析核心。1.1 在 conf.py 中的加载方式扩展要生效需先加入 Sphinx 的模块搜索路径再登记进extensions列表。pandas 的 conf.py 中sys.path.insert(0, os.path.dirname(__file__)) sys.path.insert(0, os.path.abspath(../sphinxext)) sys.path.extend( [ # numpy standard doc extensions os.path.join(os.path.dirname(__file__), .., ../.., sphinxext) ] ) extensions [ contributors, # custom pandas extension IPython.sphinxext.ipython_directive, matplotlib.sphinxext.plot_directive, numpydoc, ... ]关键点有两个一是sys.path中同时注入了doc/source、doc/sphinxext等路径使contributors可作为模块名直接导入二是contributors.py中没有main分支它只暴露setup(app)钩子由 Sphinx 在初始化时调用见下文第四节因此它既是一个可被announce.py独立导入的模块也是一个符合 Sphinx 扩展规范的插件。二、announce.py从 git 历史生成发布贡献者名单announce.py 的模块 docstring 完整描述了它的用途、依赖与用法是理解整个机制的第一手材料。2.1 用途与调用方式该脚本为发布公告生成贡献者与 PR 名单generate contributor and pull request lists for release announcements使用 GitHub v3 协议。其声明的用法为$ ./scripts/announce.py token revision rangedocstring 中给出的具体示例注意其中scripts/为文档编写年代的旧路径仓库中脚本实际位于doc/sphinxext/announce.py$ ./scripts/announce.py $GITHUB v1.11.0..v1.11.1 announce.rst即把$GITHUB环境变量中的 token 与形如v1.11.0..v1.11.1的修订区间作为参数并把结果重定向到announce.rst文件。输出格式为 UTF-8 编码的 reStructuredText代码中通过codecs.getwriter(utf8)保证见 announce.py。2.2 依赖与运行前提docstring 声明的依赖有两项gitpython用于读取本地 git 仓库日志pygithub用于从 GitHub 拉取 PR 元数据。其中 token 的用途在 docstring 中说明GitHub v3 协议需要认证 token 以获得足够的带宽无 scope 的默认只读 token 即可且 token 只展示一次建议存入环境变量。需要注意的是pygithub与 token 对应的是get_pull_requests函数见 announce.py该函数会遍历三种合并方式普通 merge、Homu 自动合并、fast-forward squash merge提取 PR 编号再调用repo.get_pull(n)获取 PR 对象但从当前源码结构看get_pull_requests并未被main()调用当前入口只输出作者名单build_string仅包含 heading、author_message、authors 三个部分PR 名单能力保留在函数层面供扩展使用。gitpython的依赖声明在仓库中有多处印证environment.yml 中注释# obtain contributors from git for whatsnewpixi.toml 中同样注明# obtain contributors from git for whatsnewrequirements-dev.txt 的gitpython一行。2.3 revision range 语法与 |HEAD 特殊处理get_authors(revision_range)首先把参数按..拆分为lst_release与cur_release见 announce.py。它支持一种扩展语法v1.0.1|HEAD含义是当cur_release中含有|时若|前是已存在的 tag 就用该 tag否则回退到HEAD——这解决了新版本 tag 尚未打上但文档构建需要先行生成贡献者名单的问题。若 tag 已存在revision_range会被重写为lst_release..cur_release保证后续 git 命令只在一个确定的范围内执行。2.4 作者收集的核心逻辑get_authors的实现展示了 pandas 如何从 git 日志中还原真实贡献者主要步骤包括两遍扫描对当前区间和上一发布区间各做两遍日志分析一遍用git log --grepCo-authored --pretty%b提取Co-authored-by:头部这些来自机器人 backport 的提交另一遍用git shortlog -s统计常规提交者announce.py剔除机器人cur.discard(Homu)/pre.discard(Homu)因为 Homu 是自动合并提交的作者announce.py贡献者改名映射CONTRIBUTOR_MAPPING {znkjnffrezna: znetbgcubravk}中的名字被 ROT13 编码避免在源码中明文暴露真实用户名运行时用codecs.decode(name, rot13)解码后完成旧名到新名的替换announce.py首度贡献标记authors [s for s in cur - pre] list(cur pre)——只在本次区间出现的作者名字后追加表示首次为本版本贡献补丁随后整体排序announce.py。2.5 输出模板build_string用textwrap.dedent拼接固定模板announce.py生成如下结构的 RSTContributors A total of %d people contributed patches to this release. People with a by their names contributed a patch for the first time. * 作者A * 作者B 模板中heading、uline与标题等长的下划线、author_message、authors四个字段由build_components组装announce.py。代码注释特意提醒不要改成 f-string以免破坏模板格式。命令行入口通过argparse接收一个revision_range位置参数announce.py。三、contributors.py把名单变成 Sphinx 指令contributors.py 是一个标准的 Sphinx 扩展核心价值在于发布说明作者无需手工粘贴名单只要在 RST 源文件中写一行指令构建时自动生成贡献者人数 名单列表。3.1 指令语法模块 docstring 给出了两种用法.. contributors:: v0.23.0..v0.23.1这是常规用法指令会把build_components的结果渲染为一段说明文字加一个 bullet list。对于 tag 尚未打上的开发版本则使用|HEAD回退语法.. contributors:: v0.23.0..v0.23.1|HEAD文档原文解释While the v0.23.1 tag does not exist, that will use the HEAD of the branch as the end of the revision range.当 v0.23.1 这个 tag 尚不存在时以分支的 HEAD 作为修订区间终点。3.2 指令实现细节ContributorsDirectivecontributors.py继承docutils.parsers.rst.Directive声明required_arguments 1必须且只需一个修订区间参数name contributors指令注册名。run()的执行流程体现了健壮性设计占位兜底若参数以x..HEAD结尾即区间尚未确定直接返回空段落与空 bullet list不报错、不中断构建异常降级捕获git.GitCommandError例如本地仓库缺少相应 tag通过self.state.document.reporter.warning(...)输出构建警告并附带行号而不是让整个文档构建失败正常渲染构造一个包含author_message的段落再为每个作者生成paragraph nodes.Text(author)的 list item最终返回[message, listnode]。setup(app)contributors.py完成注册并声明元信息def setup(app): app.add_directive(contributors, ContributorsDirective) return {version: 0.1, parallel_read_safe: True, parallel_write_safe: True}parallel_read_safe与parallel_write_safe均为True说明该指令可在 Sphinx 并行构建模式下安全执行——因为它只读本地 git 仓库不产生跨文档副作用。四、在 whatsnew 发布说明中的实际应用contributors指令是 pandas 各版本发布说明的固定组成部分。以 v0.23.0.rst 为例文件末尾的标准写法是.. _whatsnew_0.23.0.contributors: Contributors ~~~~~~~~~~~~ .. contributors:: v0.22.0..v0.23.0即每个版本页都先用锚点定义Contributors小节再以一条指令声明本版本相对上一版本的修订区间名单由构建期自动生成。对于开发版本仓库中大量使用|HEAD语法例如 v1.4.4.rst.. contributors:: v1.4.3..v1.4.4|HEAD在 v1.4.4 正式发布前指令会自动使用分支 HEAD 作为区间终点保证文档在开发期就能渲染出贡献者名单正式发版打上 tag 后同一行指令无需修改即可精确对应真实版本区间。从 whatsnew 目录 的统计看从 v0.4.x 到 v3.2.0 的 90 余个版本文件中每个文件都恰好包含一条.. contributors::指令覆盖了 pandas 全部发布历史的贡献者致谢页。五、设计要点与可复用经验纵观整个doc/sphinxext可以提炼出几个对任何维护 Sphinx 文档的活跃项目都有价值的工程实践计算与渲染分离名单生成git 分析、清洗、排序放在announce.py既可被命令行调用又可被 Sphinx 扩展以函数形式复用避免逻辑重复构建期而非维护期生成贡献者名单无需手工维护由 Sphinx 在每次构建时实时从本地 git 仓库计算杜绝忘记更新的人为错误对区间未确定的容忍|HEAD回退与x..HEAD空渲染两种机制让开发期与发版期共用同一份 RST 源文件而互不干扰失败不致命GitCommandError降级为文档构建警告而非中止保证 CI 稳定性配合parallel_read_safe扩展在并行构建下也安全发布工程自动化配合 doc/make.py 的sphinx-build调用链整个版本发布说明 贡献者致谢环节可以被脚本化、可重复执行。若要在自己的 Sphinx 项目中复用该模式只需将 contributors.py 与 announce.py 放入扩展目录、在conf.py中sys.path注入该目录并将contributors加入extensions随后即可在任意 RST 页面使用.. contributors:: tag..tag指令前提是构建环境中安装gitpython及需要 PR 名单时的pygithub并且构建时能访问目标仓库的完整 git 历史。赞分享数据分析数据科学数据处理【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址https://gitcode.com/gh_mirrors/pa/pandas点击查看免费下载相关推荐MoviePy 文档自动生成机制自定义 Sphinx autosummary 模板深度解析MoviePy 文档自动生成机制自定义 Sphinx autosummary 模板深度解析 本文聚焦 MoviePy 官方文档中 API Reference音视频视频处理音频处理librealsense pyrealsense2 API 文档自动生成机制Sphinx autosummary 模板与构建管线深度解析librealsense pyrealsense2 API 文档自动生成机制Sphinx autosummary 模板与构建管线深度解析 导读 本文聚焦 In智能硬件音视频计算机视觉pandas 文档贡献指南从 docstring 规范到 Sphinx 构建与验证pandas 文档贡献指南从 docstring 规范到 Sphinx 构建与验证 导读 本文以 pandas 仓库中的 contributing_docum数据分析数据科学数据处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/10 21:08:25 · 阅读 1.2k pandas 文档构建深度解析：doc/sphinxext 自定义 Sphinx 扩展与发布贡献者名单生成机制
数据分析数据科学数据处理【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址https://gitcode.com/gh_mirrors/pa/pandas点击查看免费下载doc/sphinxext是 pandas 文档构建体系中存放自定义 Sphinx 扩展的专用目录其中包含announce.py与contributors.py两个工具前者从 git 历史与 GitHub 数据生成发布公告所需的贡献者/PR 名单后者以 Sphinx 指令形式把名单自动渲染进whatsnew发布说明页面。本文以该目录的 README.rst 为脉络结合两个扩展的完整实现、文档配置与 90 余个发布说明中的实际调用系统讲解 pandas 如何自动化维护贡献者致谢这一发布流程环节读者可据此理解并复用到自己的 Sphinx 文档项目中。一、目录定位pandas 文档体系中的自定义扩展层pandas 文档 使用 Sphinx 构建官方 README.rst 对doc/sphinxext目录的定位只有一句话This directory contains custom sphinx extensions in use in the pandas documentation.即该目录专用于存放 pandas 文档自身开发、而非来自第三方生态的 Sphinx 扩展。目前目录下只有两个文件announce.py命令行脚本用于生成发布公告中的贡献者与 PR 名单输出 UTF-8 编码的 reStructuredTextcontributors.py真正的 Sphinx 扩展注册contributors指令将名单渲染进whatsnew各版本页面。两个文件的分工是计算与渲染的分离contributors.py通过from announce import build_components见 contributors.py直接复用announce.py中的名单计算逻辑二者共享同一套 git 分析核心。1.1 在 conf.py 中的加载方式扩展要生效需先加入 Sphinx 的模块搜索路径再登记进extensions列表。pandas 的 conf.py 中sys.path.insert(0, os.path.dirname(__file__)) sys.path.insert(0, os.path.abspath(../sphinxext)) sys.path.extend( [ # numpy standard doc extensions os.path.join(os.path.dirname(__file__), .., ../.., sphinxext) ] ) extensions [ contributors, # custom pandas extension IPython.sphinxext.ipython_directive, matplotlib.sphinxext.plot_directive, numpydoc, ... ]关键点有两个一是sys.path中同时注入了doc/source、doc/sphinxext等路径使contributors可作为模块名直接导入二是contributors.py中没有main分支它只暴露setup(app)钩子由 Sphinx 在初始化时调用见下文第四节因此它既是一个可被announce.py独立导入的模块也是一个符合 Sphinx 扩展规范的插件。二、announce.py从 git 历史生成发布贡献者名单announce.py 的模块 docstring 完整描述了它的用途、依赖与用法是理解整个机制的第一手材料。2.1 用途与调用方式该脚本为发布公告生成贡献者与 PR 名单generate contributor and pull request lists for release announcements使用 GitHub v3 协议。其声明的用法为$ ./scripts/announce.py token revision rangedocstring 中给出的具体示例注意其中scripts/为文档编写年代的旧路径仓库中脚本实际位于doc/sphinxext/announce.py$ ./scripts/announce.py $GITHUB v1.11.0..v1.11.1 announce.rst即把$GITHUB环境变量中的 token 与形如v1.11.0..v1.11.1的修订区间作为参数并把结果重定向到announce.rst文件。输出格式为 UTF-8 编码的 reStructuredText代码中通过codecs.getwriter(utf8)保证见 announce.py。2.2 依赖与运行前提docstring 声明的依赖有两项gitpython用于读取本地 git 仓库日志pygithub用于从 GitHub 拉取 PR 元数据。其中 token 的用途在 docstring 中说明GitHub v3 协议需要认证 token 以获得足够的带宽无 scope 的默认只读 token 即可且 token 只展示一次建议存入环境变量。需要注意的是pygithub与 token 对应的是get_pull_requests函数见 announce.py该函数会遍历三种合并方式普通 merge、Homu 自动合并、fast-forward squash merge提取 PR 编号再调用repo.get_pull(n)获取 PR 对象但从当前源码结构看get_pull_requests并未被main()调用当前入口只输出作者名单build_string仅包含 heading、author_message、authors 三个部分PR 名单能力保留在函数层面供扩展使用。gitpython的依赖声明在仓库中有多处印证environment.yml 中注释# obtain contributors from git for whatsnewpixi.toml 中同样注明# obtain contributors from git for whatsnewrequirements-dev.txt 的gitpython一行。2.3 revision range 语法与 |HEAD 特殊处理get_authors(revision_range)首先把参数按..拆分为lst_release与cur_release见 announce.py。它支持一种扩展语法v1.0.1|HEAD含义是当cur_release中含有|时若|前是已存在的 tag 就用该 tag否则回退到HEAD——这解决了新版本 tag 尚未打上但文档构建需要先行生成贡献者名单的问题。若 tag 已存在revision_range会被重写为lst_release..cur_release保证后续 git 命令只在一个确定的范围内执行。2.4 作者收集的核心逻辑get_authors的实现展示了 pandas 如何从 git 日志中还原真实贡献者主要步骤包括两遍扫描对当前区间和上一发布区间各做两遍日志分析一遍用git log --grepCo-authored --pretty%b提取Co-authored-by:头部这些来自机器人 backport 的提交另一遍用git shortlog -s统计常规提交者announce.py剔除机器人cur.discard(Homu)/pre.discard(Homu)因为 Homu 是自动合并提交的作者announce.py贡献者改名映射CONTRIBUTOR_MAPPING {znkjnffrezna: znetbgcubravk}中的名字被 ROT13 编码避免在源码中明文暴露真实用户名运行时用codecs.decode(name, rot13)解码后完成旧名到新名的替换announce.py首度贡献标记authors [s for s in cur - pre] list(cur pre)——只在本次区间出现的作者名字后追加表示首次为本版本贡献补丁随后整体排序announce.py。2.5 输出模板build_string用textwrap.dedent拼接固定模板announce.py生成如下结构的 RSTContributors A total of %d people contributed patches to this release. People with a by their names contributed a patch for the first time. * 作者A * 作者B 模板中heading、uline与标题等长的下划线、author_message、authors四个字段由build_components组装announce.py。代码注释特意提醒不要改成 f-string以免破坏模板格式。命令行入口通过argparse接收一个revision_range位置参数announce.py。三、contributors.py把名单变成 Sphinx 指令contributors.py 是一个标准的 Sphinx 扩展核心价值在于发布说明作者无需手工粘贴名单只要在 RST 源文件中写一行指令构建时自动生成贡献者人数 名单列表。3.1 指令语法模块 docstring 给出了两种用法.. contributors:: v0.23.0..v0.23.1这是常规用法指令会把build_components的结果渲染为一段说明文字加一个 bullet list。对于 tag 尚未打上的开发版本则使用|HEAD回退语法.. contributors:: v0.23.0..v0.23.1|HEAD文档原文解释While the v0.23.1 tag does not exist, that will use the HEAD of the branch as the end of the revision range.当 v0.23.1 这个 tag 尚不存在时以分支的 HEAD 作为修订区间终点。3.2 指令实现细节ContributorsDirectivecontributors.py继承docutils.parsers.rst.Directive声明required_arguments 1必须且只需一个修订区间参数name contributors指令注册名。run()的执行流程体现了健壮性设计占位兜底若参数以x..HEAD结尾即区间尚未确定直接返回空段落与空 bullet list不报错、不中断构建异常降级捕获git.GitCommandError例如本地仓库缺少相应 tag通过self.state.document.reporter.warning(...)输出构建警告并附带行号而不是让整个文档构建失败正常渲染构造一个包含author_message的段落再为每个作者生成paragraph nodes.Text(author)的 list item最终返回[message, listnode]。setup(app)contributors.py完成注册并声明元信息def setup(app): app.add_directive(contributors, ContributorsDirective) return {version: 0.1, parallel_read_safe: True, parallel_write_safe: True}parallel_read_safe与parallel_write_safe均为True说明该指令可在 Sphinx 并行构建模式下安全执行——因为它只读本地 git 仓库不产生跨文档副作用。四、在 whatsnew 发布说明中的实际应用contributors指令是 pandas 各版本发布说明的固定组成部分。以 v0.23.0.rst 为例文件末尾的标准写法是.. _whatsnew_0.23.0.contributors: Contributors ~~~~~~~~~~~~ .. contributors:: v0.22.0..v0.23.0即每个版本页都先用锚点定义Contributors小节再以一条指令声明本版本相对上一版本的修订区间名单由构建期自动生成。对于开发版本仓库中大量使用|HEAD语法例如 v1.4.4.rst.. contributors:: v1.4.3..v1.4.4|HEAD在 v1.4.4 正式发布前指令会自动使用分支 HEAD 作为区间终点保证文档在开发期就能渲染出贡献者名单正式发版打上 tag 后同一行指令无需修改即可精确对应真实版本区间。从 whatsnew 目录 的统计看从 v0.4.x 到 v3.2.0 的 90 余个版本文件中每个文件都恰好包含一条.. contributors::指令覆盖了 pandas 全部发布历史的贡献者致谢页。五、设计要点与可复用经验纵观整个doc/sphinxext可以提炼出几个对任何维护 Sphinx 文档的活跃项目都有价值的工程实践计算与渲染分离名单生成git 分析、清洗、排序放在announce.py既可被命令行调用又可被 Sphinx 扩展以函数形式复用避免逻辑重复构建期而非维护期生成贡献者名单无需手工维护由 Sphinx 在每次构建时实时从本地 git 仓库计算杜绝忘记更新的人为错误对区间未确定的容忍|HEAD回退与x..HEAD空渲染两种机制让开发期与发版期共用同一份 RST 源文件而互不干扰失败不致命GitCommandError降级为文档构建警告而非中止保证 CI 稳定性配合parallel_read_safe扩展在并行构建下也安全发布工程自动化配合 doc/make.py 的sphinx-build调用链整个版本发布说明 贡献者致谢环节可以被脚本化、可重复执行。若要在自己的 Sphinx 项目中复用该模式只需将 contributors.py 与 announce.py 放入扩展目录、在conf.py中sys.path注入该目录并将contributors加入extensions随后即可在任意 RST 页面使用.. contributors:: tag..tag指令前提是构建环境中安装gitpython及需要 PR 名单时的pygithub并且构建时能访问目标仓库的完整 git 历史。赞分享数据分析数据科学数据处理【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址https://gitcode.com/gh_mirrors/pa/pandas点击查看免费下载相关推荐MoviePy 文档自动生成机制自定义 Sphinx autosummary 模板深度解析MoviePy 文档自动生成机制自定义 Sphinx autosummary 模板深度解析 本文聚焦 MoviePy 官方文档中 API Reference音视频视频处理音频处理librealsense pyrealsense2 API 文档自动生成机制Sphinx autosummary 模板与构建管线深度解析librealsense pyrealsense2 API 文档自动生成机制Sphinx autosummary 模板与构建管线深度解析 导读 本文聚焦 In智能硬件音视频计算机视觉pandas 文档贡献指南从 docstring 规范到 Sphinx 构建与验证pandas 文档贡献指南从 docstring 规范到 Sphinx 构建与验证 导读 本文以 pandas 仓库中的 contributing_docum数据分析数据科学数据处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考