CANN/pyasc API文档自动生成工具使用指南

API文档自动生成工具使用指南【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc概述本项目采用Sphinx工具通过提取项目 Python 代码如模块、类、函数中的docstring文档字符串自动生成标准化的 Python API 文档。该文档可清晰展示代码的功能说明、参数定义、返回值类型及使用示例旨在降低文档维护成本确保代码与文档的一致性。当前已在项目根目录下创建docs目录并完成核心配置文件conf.py、index.rst、Makefile等的初始化用户可直接基于现有框架完成文档的更新与生成。环境准备以开发者模式或普通模式安装pyasc包、文档生成工具所需的依赖。开发者模式在项目根目录下执行如下命令将同时安装pyasc包和文档生成工具所需的依赖。pip install -e .[docs]普通模式在项目根目录下执行如下命令分别安装pyasc包、Sphinx及相关插件。pip install . pip install sphinx sphinx-rtd-theme sphinx-autodoc-typehints pip install sphinx-markdown-builder文档生成核心文件说明docs目录下的关键文件功能如下请勿随意删除核心文件如需修改请参考下方指引。文件名作用说明conf.pySphinx 核心配置文件包含文档主题、扩展插件、项目信息如名称、版本等配置index.rst文档首页入口文件定义文档的目录结构如模块列表、子文档链接Makefile自动化脚本文件提供make markdown和make html等命令用于快速生成文档python-apiPython前段模块索引文件用于聚合项目中所有待提取 docstring 的 Python 模块_static配置相关css格式仅影响html静态网页生成格式标准 API 文档生成流程首次生成或全量更新文档时执行以下步骤进入 docs 目录在项目根目录下打开终端切换到docs目录。cd docs可选更新模块索引若项目新增或删除了 Python 模块需更新python-api目录下对应的rst格式模块索引文件确保该模块已被包含或已删除。rst文件格式示例如下。项目模块列表 .. toctree:: :maxdepth: 4 模块1路径如 src.utils 模块2路径如 src.core生成文档执行Makefile中的markdown或html命令Sphinx 会自动提取docstring并生成 Markdown 文档或 html 静态网页。根据需要执行相应命令。# Linux/Mac 环境 make markdown # 生成markdown格式文档 make html # 生成html格式文档 # Windows 环境无 Make 工具时 sphinx-build -b markdown . /_build/markdown # 生成markdown格式文档 sphinx-build -b html . /_build/html # 生成html格式文档查看生成的文档文档生成成功后会保存在docs/_build/markdown或docs/_build/html目录下直接打开index.md或index.html文件即可查看完整的 API 文档。更新API文档流程当用户修改了 Python 文件如新增函数、更新docstring内容无需执行API文档生成的全量流程仅需执行以下简化步骤确认docstring内容确保修改后的函数 / 类 / 模块已按规范编写docstring推荐 Google 风格或 NumPy 风格规范细节可参考Google 风格官方指南、NumPy 风格官方指南docstring内容示例如下。def add(dst: LocalTensor, src0: LocalTensor, src1: LocalTensor, *args, **kwargs) - None: 按元素求和。 **对应的Ascend C函数原型** .. code-block:: c template typename T __aicore__ inline void Add(const LocalTensorT dst, const LocalTensorT src0, const LocalTensorT src1, const int32_t count); .. code-block:: c template typename T, bool isSetMask true __aicore__ inline void Add(const LocalTensorT dst, const LocalTensorT src0, const LocalTensorT src1, uint64_t mask[], const uint8_t repeatTimes, const BinaryRepeatParams repeatParams); .. code-block:: c template typename T, bool isSetMask true __aicore__ inline void Add(const LocalTensorT dst, const LocalTensorT src0, const LocalTensorT src1, uint64_t mask, const uint8_t repeatTimes, const BinaryRepeatParams repeatParams); **参数说明** - is_set_mask是否在接口内部设置mask模式和mask值。 - dst: 目的操作数。类型为LocalTensor支持的TPosition为VECIN/VECCALC/VECOUT。 - src0, src1: 源操作数。类型为LocalTensor支持的TPosition为VECIN/VECCALC/VECOUT。 - count: 参与计算的元素个数。 - mask: 用于控制每次迭代内参与计算的元素。 - repeat_times: 重复迭代次数。 - params: 控制操作数地址步长的参数。 **返回值说明**若无则无需补充 ... **调用示例** - tensor高维切分计算样例-mask连续模式 .. code-block:: python mask 128 # repeat_times 4一次迭代计算128个数共计算512个数 # dst_blk_stride, src0_blk_stride, src1_blk_stride 1单次迭代内数据连续读取和写入 # dst_rep_stride, src0_rep_stride, src1_rep_stride 8相邻迭代间数据连续读取和写入 params asc.BinaryRepeatParams(1, 1, 1, 8, 8, 8) asc.add(dst, src0, src1, maskmask, repeat_times4, repeat_paramsparams) - tensor高维切分计算样例-mask逐bit模式 .. code-block:: python mask [uint64_max, uint64_max] # repeat_times 4一次迭代计算128个数共计算512个数 # dst_blk_stride, src0_blk_stride, src1_blk_stride 1单次迭代内数据连续读取和写入 # dst_rep_stride, src0_rep_stride, src1_rep_stride 8相邻迭代间数据连续读取和写入 params asc.BinaryRepeatParams(1, 1, 1, 8, 8, 8) asc.add(dst, src0, src1, maskmask, repeat_times4, repeat_paramsparams) - tensor前n个数据计算样例 .. code-block:: python asc.add(dst, src0, src1, count512) builder global_builder.get_ir_builder() op_impl(add, dst, src0, src1, args, kwargs, builder.create_asc_AddL0Op, builder.create_asc_AddL1Op, builder.create_asc_AddL2Op)进入docs目录并重新生成文档在docs目录下执行如下文档生成命令Sphinx 将自动识别代码变更并更新文档内容。根据需要执行相应命令。# Linux/Mac 环境 cd docs make markdown # 更新markdown格式文档 make html # 更新html格式文档 # Windows 环境 cd docs sphinx-build -b markdown . /_build/markdown # 更新markdown格式文档 sphinx-build -b html . /_build/html # 更新html格式文档验证文档更新结果重新打开docs/_build/markdown/index.md或docs/_build/html/index.html导航到该修改的模块 / 函数确认文档内容已同步更新。常见问题FAQ问题执行make markdown时提示 “No module named xxx”解决确保待提取的 Python 模块已在项目环境变量中可在conf.py中添加路径配置。import os import sys # 将项目根目录添加到 Python 路径根据实际结构调整 sys.path.insert(0, os.path.abspath(../src))问题生成的文档中缺少部分函数 / 类的说明解决检查以下两点确认函数 / 类的docstring格式符合 Sphinx 识别规范参考上述Google 风格或 NumPy 风格规范确认对应的模块已添加到python-api目录中对应rst文件的toctree列表中。问题生成的文档中内容格式显示错误解决检查docstring中内容对齐格式。 **参数说明** - mode_number合入位置参数取值范围modeNumber∈[0, 5] # 不同层级之间添加一个空行 - 0合入x1 # 当前层级标题应与上一层级标题正文内容对齐 - 1合入y1 - 2合入x2 - 3合入y2 - 4合入score - 5合入label **调用示例** .. code-block:: python # 代码块应与上一行正文内容对齐 a 1 b 2 c a b - tensor前n个数据计算样例 .. code-block:: python # 代码块应与上一行正文内容对齐 asc.add(dst, src0, src1, count512) 扩展与定制若需自定义文档风格或功能可修改以下配置支持更多 docstring 风格在conf.py的extensions中添加sphinx.ext.napoleon支持 Google/NumPy 风格 docstring。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考