科学计算数据分析【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址https://gitcode.com/gh_mirrors/nu/numpy点击查看免费下载本指南以 NumPy 官方开发者文档 howto-docs.rst 为骨架系统讲解如何为 NumPy 贡献文档从识别文档缺口、修复 docstring 缺陷到用 numpydoc 规范撰写 Python 文档字符串再到用 Doxygen Breathe Sphinx 三件套为 C/C 核心代码撰写并渲染 API 文档以及使用.. legacy::指令标注过期模块。读完本文你将掌握一套完整、可落地、与 NumPy 源码树直接对应的文档贡献工作流。文档团队会议与社区协作入口NumPy 社区把改进文档当作明确目标定期通过 Zoom 召开文档会议会议日期通过 numpy-discussion 邮件列表公布任何人均可参加。会议记录发布在 hackmd.io并归档于 NumPy Archive 仓库。如果你需要有人带你完成第一次贡献可以在会议上直接求助——这是新手入门最友好的渠道。贡献文档不只有写一条路报告文档缺陷同样是重要贡献。下文会分别介绍修复缺陷与撰写新页面两条路径以及它们各自的技术规范。修复文档缺陷优先级与处理方式缺陷的优先级排序NumPy 希望优先修复那些最值得投入的文档问题优先级如下技术性错误最高优先级docstring 遗漏了某个参数、函数/参数/方法的描述有误等。这类缺陷容易确认、容易修正且对用户价值最大。结构性缺陷次高优先级如文档中的失效链接broken links。拼写错误欢迎反馈但可能无法被及时修复。措辞问题明显的措辞错误如漏掉一个 not归入拼写类但其他改写——即便是语法层面的——需要判断力把关门槛更高建议先在 issue 中抛出方案、试探社区意见。修复方式如果你熟悉 GitHub 流程直接提交 Pull RequestPR否则请先开 issue 说明问题。C 扩展模块的 docstring 藏在哪儿一个容易踩坑的细节numpy.ndarray.transpose、numpy.array等定义在 C 扩展模块中的函数/对象其 docstring 并不写在 C 源码里而是单独定义在 numpy/_core/_add_newdocs.py中。因此当你需要修正这类对象的文档时应前往该文件修改对应的 Python 字符串而不是去.c文件里找。这一设计在仓库中同样体现在_add_newdocs_scalars.py标量类型文档等配套文件上参见 numpy/_core 目录并在 meson.build 中参与构建。贡献新页面从想法到落地你自己使用文档时的困惑就是文档最需要改进的地方。想写一篇缺失的文档先到邮件列表征求意见获取反馈后再动笔只想指出缺口直接开 issue 即可官方文档以 issue #15760 为例展示这种流程。如果你在寻找选题正式的文档路线图是 NumPy Enhancement ProposalNEP即NEP 44见 doc/source/neps 目录下的 nep-0044-restructuring-numpy-docs.rst。它列出了文档需要帮助的领域和期望新增的内容其中包括Jupyter Notebook 教程。教程的独立投稿渠道NumPy Tutorials除了随源码树分发的文档外你还可以把 Jupyter Notebook 格式的内容提交到 NumPy Tutorials 页面。这些教程和教学材料由 NumPy 项目维护面向自学与课堂教学双重场景开发工作在独立的 numpy-tutorials 仓库进行可以查看现有 notebook、开 issue 提议新主题、或通过 PR 提交自己的教程。文档框架Diátaxis 四象限编写实用文档有公式可循四种公式几乎覆盖所有场景因为文档恰好分为四种类型文档类型定位tutorial教程面向初学者通过一步步操作完成学习how-to guide操作指南面向有明确任务的使用者解决具体问题explanation解释面向需要理解原理的读者讲清为什么reference参考面向查证需求的用户精确描述接口细节这一洞察来自 Daniele Procida 的 Diátaxis 框架。开始撰写或提出一篇新文档时先明确它属于哪一类——这决定了文档的结构、语气与目标读者。其他贡献注意事项语言与粗糙初稿英语不是母语、只能写出粗略草稿都没关系开源是社区协作社区会帮你完善图片与真实数据能显著增强文档表现力但必须确保授权合规、可获取数据格式目前 NumPy 只接受其他 Python 科学库pandas、SciPy、Matplotlib同样使用的数据格式提交方式NumPy 文档保存在源码树中要进入文档库你需要拉取源码树、本地构建详见下文构建文档然后提交 PR。不熟悉 GitHub/PR 可以阅读仓库中的 开发工作流文档标记语言NumPy 文档使用reStructuredTextrST比 Markdown 更复杂Sphinx 负责将 rST 转换为 HTML 等格式。间接贡献同样被认可你在博客写教程、做 YouTube 视频、在 Stack Overflow 等网站回答问题都算为 NumPy 做出了贡献遇到适合补充进官方文档的外部材料也可以通过 issue 告知维护者。构建文档本地验证你的修改要让贡献被合并本地必须能成功构建文档。构建前置要求如下NumPy 本体文档很大一部分通过import numpy读取 docstring 生成因此必须先构建并安装对应版本的 NumPy且每次拉取最新源码后都要重新构建安装保证 NumPy 版本与 git 仓库版本同步。可安装到临时目录并设置PYTHONPATH或使用 conda/virtualenv/venv 新建虚拟环境安装。依赖除 Doxygen 外所有依赖可用一条命令安装pip install -r requirements/doc_requirements.txt必要时可安装文档依赖的开发版pip install --pre --force-reinstall --extra-index-url \ https://pypi.anaconda.org/scientific-python-nightly-wheels/simple \ -r requirements/doc_requirements.txt构建体系使用 Sphinx Doxygen另需 Matplotlib 自带的plot_directiveSphinx 扩展渲染示例图、numpydoc 渲染 docstringSciPy 也被安装部分文档章节依赖 SciPy 函数。Doxygen 建议安装高于 1.8.10 的版本否则构建时可能出现警告。 3.子模块通过 git 获取的源码还需拉取子模块git submodule update --init。一切就绪后一键构建spin docs该命令会从源码构建 NumPy如果尚未构建并运行 Sphinx 生成 HTML 文档输出到doc/build/html子目录。官方发布在 numpy.org/doc 的 HTML 与 PDF 文档则由make dist构建。详细流程参见 如何构建 API 与参考文档。文档风格用户文档与 docstring 规范用户文档风格用户指南总体遵循Google developer documentation style guideGoogle 未覆盖或社区倾向不同之处由NumPy 风格补充当前规则包括index的复数用indices而非indexes沿用numpy.indices的先例为保持一致matrix的复数用matrices两者都未充分解决的语法问题以最新版Chicago Manual of Style的 Grammar and Usage 章节为准社区欢迎随时指出应加入 NumPy 风格规则的案例。docstring必须使用 numpydoc 约定使用 Sphinx 配合 NumPy 约定时应启用numpydoc扩展docstring 才能被正确处理。例如Sphinx 会从 docstring 中提取Parameters章节并转换为字段列表而纯 Sphinx 遇到 NumPy docstring 约定如-------------式节标题会产生 rST 错误numpydoc 可以避免这些问题。两条重要约定示例中无需import numpy as npNumPy 文档内的示例默认已有 numpy 环境不要画蛇添足格式必须遵循 numpydoc 的格式化标准与官方示例。关于 docstring 中每个字段Parameters、Returns、Raises、Examples 等的写法可进一步参考仓库中的 EXAMPLE_DOCSTRING.rst。为 C/C 代码撰写文档Doxygen Breathe Sphinx 三步走NumPy 的核心如numpy/_core/src/下的 C 实现用Doxygen解析特殊格式的 C/C 注释块生成 XML 文件再由Breathe转换为 rST最终由Sphinx渲染成 HTML。整个文档化流程分三步。第一步编写注释块尚无强制规定的注释风格但Javadoc 风格与现有未索引注释块更相似因而更受青睐。Javadoc 风格示例如下源码见 doc/source/dev/examples/doxy_func.h/** * This a simple brief. * * And the details goes here. * Multi lines are welcome. * * param num leave a comment for parameter num. * param str leave a comment for the second parameter. * return leave a comment for the returned value. */ int doxy_javadoc_example(int num, const char *str);该函数在文档中通过.. doxygenfunction:: doxy_javadoc_example指令渲染。对于行注释可以使用三斜杠///例如 doc/source/dev/examples/doxy_class.hpp 中的模板类/** * Template to represent limbo numbers. * * Specializations for integer types that are part of nowhere. * It doesnt support with any real types. * * param Tp Type of the integer. Required to be an integer type. * param N Number of elements. */ templatetypename Tp, std::size_t N class DoxyLimbo { public: /// Default constructor. Initialize nothing. DoxyLimbo(); /// Set Default behavior for copy the limbo. DoxyLimbo(const DoxyLimboTp, N l); /// Returns the raw data for the limbo. const Tp *data(); protected: Tp p_data[N]; /// Example for inline comment. };该类的文档通过.. doxygenclass:: DoxyLimbo指令渲染。常用 Doxygen 标签速查标签作用brief开启一段简短描述段落。由于 Doxygen 配置中启用了JAVADOC_AUTOBRIEF文档块的第一句话默认会被当作简短描述details开启详细描述段落。也可以用空行开启新段落此时无需detailsparam描述函数参数。Doxygen 会校验参数是否存在若某个参数缺少文档会给出警告return描述函数返回值。相邻的多个return会合并为一段遇到空行或其他分节命令时结束code/endcode包裹代码块代码块会按源代码而非普通文本解析rst/endrst包裹一段 reST 标记rst/endrst的威力见 doc/source/dev/examples/doxy_rst.h/** * A comment block contains reST markup. * rst * .. note:: * * Thanks to Breathe_, we were able to bring it to Doxygen_ * * Some code example:: * * int example(int x) { * return x * 2; * } * endrst */ void doxy_reST_example(void);第二步喂给 Doxygen.doxyfile 子配置文件Doxygen不会自动收集所有头文件必须把需要处理的 C/C 头文件路径加进 Doxygen 的子配置文件中。这些子配置文件统一命名为.doxyfile通常位于包含待文档化头文件的目录附近如果距头文件 2 层深度内没有现成配置需要新建一个。子配置文件可以接受 Doxygen 的任何配置选项但不能用覆盖或重新初始化已有选项只能用追加运算符。仓库中的真实子配置文件可以佐证这一约定例如 doc/source/dev/examples/.doxyfileINPUT CUR_DIR INCLUDE_PATH CUR_DIR其中CUR_DIR是一个模板常量返回子配置文件所在目录的路径。核心头文件目录的配置numpy/_core/include/numpy/.doxyfile展示了如何通过PREDEFINED为解析器预定义宏INCLUDE_PATH CUR_DIR PREDEFINED NPY_INTERNAL_BUILD而 numpy/_core/src/common/.doxyfile 则用于收集核心实现目录中的头文件。一个典型的子配置文件长这样# 指定某些头文件 INPUT CUR_DIR/header1.h \ CUR_DIR/header2.h # 添加某路径下的所有头文件 INPUT CUR_DIR/to/headers # 定义某些宏 PREDEFINED C_MACRO(X)X # 启用某些条件编译分支 PREDEFINED NPY_HAVE_FEATURE \ NPY_HAVE_FEATURE2第三步Breathe 包含指令把 Doxygen 输出转成 rSTBreathe 提供丰富的自定义指令把 Doxygen 生成的文档转换为 rST 文件。常用指令如下。doxygenfunction为单个函数生成输出函数名在项目中必须唯一.. doxygenfunction:: function name :outline: :no-link:doxygenclass为单个类生成输出在标准 project/path/outline/no-link 选项之外还支持 members、protected-members、private-members、undoc-members、membergroups 与 members-only 选项.. doxygenclass:: class name :members: [...] :protected-members: :private-members: :undoc-members: :membergroups: ... :members-only: :outline: :no-link:doxygennamespace为命名空间内容生成输出额外支持 content-only、members、protected-members、private-members、undoc-members 选项。引用嵌套命名空间时必须给出完整路径如foo::bar表示 foo 内的 bar 命名空间.. doxygennamespace:: namespace :content-only: :outline: :members: :protected-members: :private-members: :undoc-members: :no-link:doxygengroup为 Doxygen 分组生成输出分组通过在源码注释中写特定 Doxygen 标记声明额外支持 content-only、members、protected-members、private-members、undoc-members 与 inner 选项.. doxygengroup:: group name :content-only: :outline: :members: :protected-members: :private-members: :undoc-members: :no-link: :inner:legacy 指令标注过期 API如果某个函数、模块或 API 处于legacy遗留模式——即为向后兼容而保留、但不建议在新代码中使用——可以在文档中使用.. legacy::指令。无参数使用时生成默认提示文案。该指令的实际渲染逻辑实现在 doc/source/conf.py 的LegacyDirective类中第 172–221 行默认把对象当作submodule生成类似 This submodule is considered legacy and will no longer receive updates. This could also mean it will be removed in future NumPy versions. 的提示并以 Legacy 为标题、套用admonition-legacyCSS 类渲染成警示块推荐附加自定义信息例如指明替代的新 API自定义内容会追加到默认文案之后.. legacy:: For more details, see :ref:distutils-status-migration.可选参数用于指定遗留对象类型函数、方法等而非默认的 submodule.. legacy:: function持续学习文档写作资源Write the Docs领先的技术写作者组织举办会议、提供学习资源、运营 Slack 频道Google 技术写作资源Every engineer is also a writer提供面向开发者的免费在线课程涵盖文档规划与写作Software Carpentry面向研究人员的软件教学组织其课程网站也系统讲解了如何有效呈现技术想法。总而言之为 NumPy 贡献文档是一条从反馈到深度贡献的递进路径你既可以开 issue 报告缺陷也可以直接修复_add_newdocs.py中的 C 扩展 docstring既能按 Diátaxis 框架撰写教程与解释性文档也能用 Javadoc 风格注释 .doxyfile子配置 Breathe 指令为 C/C 核心代码补齐 API 参考。所有修改最终都要经过本地spin docs构建验证后以 PR 提交——这正是 NumPy 文档保持高质量、可溯源的原因所在。赞分享科学计算数据分析【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址https://gitcode.com/gh_mirrors/nu/numpy点击查看免费下载相关推荐llmware 文档贡献指南numpy 风格 Docstring 规范与 Jekyll 文档站本地构建实战llmware 文档贡献指南numpy 风格 Docstring 规范与 Jekyll 文档站本地构建实战 本文基于 llmware 仓库中的 贡献文档规范RAGAI AgentAI 应用后端NLPNumPy 文档架构重组NEP 44全解Diátaxis 四象限文档体系与仓库落地实践NumPy 文档架构重组NEP 44全解Diátaxis 四象限文档体系与仓库落地实践 导读 NEP 44NumPy Enhancement Propo科学计算数据分析文档改进清单4.5.0文档改进清单4.5.0 必须修复 README.md中Barcode readers章节仍引用Quagga2 label printing.md未提及W后端前端上一篇Tailwind-merge 主题系统完全指南深度解析 fromTheme 函数的强大功能下一篇Shiny与AI集成实战指南7个步骤构建智能数据科学应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考