Flax 文档构建与写作实战指南Sphinx、doctest 与 docstring 规范全解析【免费下载链接】flaxFlax is a neural network library for JAX that is designed for flexibility.项目地址: https://gitcode.com/GitHub_Trending/fl/flaxFlax 是一个面向 JAX 的神经网络库其核心是新一代NNXAPI使用 Python 引用语义表达模型。本指南以仓库中 docs_nnx/README.md 为主线系统讲解 Flax NNX 文档体系的结构、本地构建流程Sphinx Makefile、嵌入代码测试机制doctest以及 docstring 编写规范并辅以仓库源码conf.py、Makefile、flax_module.py 等进行纵深剖析。读完本文你将能独立在本地构建 Flax 文档、运行嵌入代码测试并写出符合 Flax 社区标准、可被自动测试与自动生成 API 参考的 docstring。一、Flax 文档在哪里Flax 的官方文档托管于在线文档站而当前仓库中维护着两份完整的文档源码目录docs/面向旧版Flax LinenAPI 的文档docs_nnx/面向新一代Flax NNXAPI 的文档是本指南的核心对象。从 docs_nnx/conf.py 的站点公告配置可以看到当前文档站专门标注了 This site covers the new Flax NNX API并引导读者前往旧版 Linen API 站点说明 NNX 文档站是 Flax 文档当前的主线。docs_nnx 目录内的内容非常丰富主要包括入门教程nnx_basics.md、mnist_tutorial.md、key_concepts.md深入指南guides/包含 transforms、filters、checkpointing、data_loaders 等主题、migrating/Linen 到 NNX 迁移指南设计文档与 FLIPflip/ 目录存放 Flax 特性提案Feature Lifecycle/Improvement ProposalsAPI 参考api_reference/ 以flax.nnx模块为单位组织的 rst 文件示例examples/minigpt、vit_training、gemma 等 Notebook导航与目录文件index.rst、guides_basic.rst、guides_advanced.rst、nnx_glossary.rst、why.rst。从 index.rst 的隐藏 toctree 可以看到文档站的完整导航结构它决定了在线文档的目录组织顺序。二、在本地构建 Flax 文档README.md 给出了完整的本地构建流程下面结合仓库实际配置逐步展开。2.1 安装依赖克隆仓库后在flax主目录下用uv安装带文档依赖的可编辑版本git clone 仓库地址 cd flax uv pip install -e .[docs].[docs]对应 pyproject.toml 中声明的docs可选依赖组它锁定了文档构建所需的关键工具版本包括sphinx6.2.1文档构建引擎sphinx-book-themeHTML 主题对应 conf.py 中的html_thememyst_nb支持 Markdown 与 Jupyter Notebook.ipynb的 MyST 解析器jupytext1.13.8用于 Notebook 与 Markdown 双份文件的同步sphinx-design提供 index 页面中的卡片式布局card/grid 指令。从 pyproject.toml 还可以看到 Flax 主包本身的运行时依赖jax0.10.0、optax、orbax-checkpoint、treescope等构建文档前需要确保这些依赖就绪。2.2 执行构建在docs_nnx目录下运行make html该命令由 docs_nnx/Makefile 定义它是最小化的 Sphinx MakefileSPHINXBUILD默认指向sphinx-buildSOURCEDIR .表示以docs_nnx目录为源码根BUILDDIR _build指定输出目录。构建成功后会出现提示The HTML pages are in _build/html.产物位于docs_nnx/_build/html可以用浏览器打开预览。需要说明的是README.md 中预览 docs/_build/html的表述对应的是旧目录约定在本仓库中构建输出实际位于docs_nnx/_build/html。2.3 文件变更时自动重建可选如果需要边改边看效果可以安装entr工具它能在文件变化时触发命令然后运行find ../ ! -regex .*/[\.|\_].* | entr -s make html该命令会监控docs_nnx上级目录即仓库根中所有非隐藏文件一旦有变更便自动重新执行make html。注意由于构建输出_build目录以下划线开头会被正则排除避免触发无限重建。2.4 构建配置与笔记本执行策略构建行为由 docs_nnx/conf.py 全面控制几个值得注意的配置点源文件后缀顺序conf.py 中source_suffix [.rst, .ipynb, .md]特意把.ipynb排在.md之前。注释说明这是因为每个 Notebook 都有.md与.ipynb双份拷贝未执行的 Notebook 输出只存在于.ipynb中因此必须优先转换.ipynbNotebook 执行策略conf.py 通过环境变量NB_EXECUTION_MODE控制默认off即构建时不执行 Notebooknb_execution_timeout 100设定单 cell 超时nb_execution_excludepatterns列出了需要排除执行的 Notebook如会超时的mnist_tutorial.ipynb、依赖旧版 flax 的transfer_learning.ipynb等且nb_execution_raise_on_error True一旦执行出错会直接让构建失败从而让 CI 及时捕获问题环境变量conf.py 在构建时设置os.environ[FLAX_DOC_BUILD] true供库内代码判断当前是否处于文档构建上下文自定义扩展conf.py 注册了codediff与flax_module两个仓库自带扩展路径分别为 docs_nnx/_ext/codediff.py 与 docs_nnx/_ext/flax_module.py通过sys.path.append(os.path.abspath(./_ext))加入搜索路径。2.5 自定义扩展与 API 参考生成Flax 的 API 参考不是手写的而是通过 Sphinx autosummary 自动从源码 docstring 生成的flax_module 指令docs_nnx/_ext/flax_module.py 提供.. flax_module::指令用法为.. flax_module:: :module: flax.linen :class: Dense它通过importlib导入指定模块、取出类对象调用generate_autosummary_content渲染模板从而把类的 docstring、方法与属性自动展开成文档页面Sphinx 补丁docs_nnx/conf_sphinx_patch.py 对 Sphinx 的generate_autosummary_content打了补丁核心只加了一行ns[annotations] list(getattr(obj, __annotations__, {}).keys())补丁注释conf_sphinx_patch.py说明这是为了让 autosummary 提供annotations变量从而在模板中把类注解属性从方法列表中排除模板docs_nnx/_templates/autosummary/flax_module.rst 定义了类的文档渲染模板自动输出automethod:: __call__并遍历方法列表过滤掉__init__、setup以及作为注解的属性。这意味着你在源码 docstring 里写的每一行注释都会直接进入在线 API 文档这也正是下文 docstring 规范如此重要的原因。三、运行嵌入代码测试doctest3.1 doctest 机制Flax 文档中的嵌入代码示例不是摆设而是会作为测试在 CI 中真实运行。其机制基于 Python 标准库的doctest与 Sphinx 的sphinx.ext.doctest扩展在 conf.py 中启用。在docs_nnx目录下运行make doctest即可在本地执行所有文档中的 doctest 块。3.2 doctest 全局环境conf.py 为 doctest 准备了全局初始化脚本doctest_global_setupimport jax jax.config.update(jax_num_cpu_devices, 8) import jax.numpy as jnp from flax import nnx这保证了所有 doctest 块默认就可以直接使用jax、jnp、nnx并且模拟 8 个 CPU 设备便于测试 SPMD/并行相关示例。此外脚本还通过自定义logging.Formatter过滤掉 absl 日志中SaveArgs.aggregate is deprecated等噪音消息避免它们破坏 doctest 的输出比对。同时 conf.py 设置了doctest_default_flags doctest.NORMALIZE_WHITESPACE允许忽略空白差异pyproject.toml 中doctest_optionflags [NUMBER, ELLIPSIS]进一步放宽了对浮点精度和省略号输出的要求。3.3 在文档中编写 doctest在 reStructuredText 或 docstring 中使用::引入代码块并缩进即可被 doctest 捕获Example code之前的说明文字可以随意替换只要满足冒号加换行、代码缩进的格式即可Example code:: def sum(a, b): return a b sum(0, 1)在 docstring 中的写法类似双引号包裹注释形式配合 Sphinx 的代码高亮# Example code:: # # def sum(a, b): # return a b # # sum(0, 1)四、编写高质量 docstringFlax 社区规范README.md 强调docstring 应当信息充分。对于实现新功能的Module仅提供一行解释是不够的We prefer to err on the side of too much documentation than too little并且强烈鼓励在 docstring 中加入示例代码让用户直接看到用法。由于 API 参考页面由 docstring 自动生成docstring 质量直接决定文档质量。4.1 使用 code font写行内代码时使用双反引号例如 str。参数名以及True、None等对象、字符串字面量通常都应放入行内代码This returns a str object.4.2 创建交叉引用cross-reference使用 Sphinx 的引用语法可以链接到其他类、函数与方法其中obj_type取class、func或meth之一# 第一种方法 # obj_type:path_to_obj # 第二种方法带显示名称 # :obj_type:description path_to_obj当目标路径很长时推荐使用第二种方法。官方示例# 引用 flax.linen.Module 类 :class:flax.linen.Module # 引用本地函数 my_func :func:my_func # 引用 Module.apply() 方法 :meth:Module.apply() flax.linen.Module.apply创建超链接的语法如下注意结尾是双下划线Link to Google http://www.google.com__4.3 参数与属性标注规范类属性使用Attributes:标签方法参数使用Args:标签所有属性和参数都必须标注类型。仓库中的DenseGeneral定义于 flax/linen/linear.py是这一规范的典型范例其 docstring 完整展示了每个字段的含义、类型与默认值class DenseGeneral(Module): A linear transformation with flexible axes. Attributes: features: int or tuple with number of output features. axis: int or tuple with axes to apply the transformation on. For instance, (-2, -1) will apply the transformation to the last two axes. batch_dims: tuple with batch axes. use_bias: whether to add a bias to the output (default: True). dtype: the dtype of the computation (default: float32). kernel_init: initializer function for the weight matrix. bias_init: initializer function for the bias. precision: numerical precision of the computation see jax.lax.Precision for details. features: Union[int, Iterable[int]] axis: Union[int, Iterable[int]] -1 batch_dims: Iterable[int] () use_bias: bool True dtype: Dtype jnp.float32 kernel_init: Callable[[PRNGKey, Shape, Dtype], Array] default_kernel_init bias_init: Callable[[PRNGKey, Shape, Dtype], Array] zeros precision: Any None compact def __call__(self, inputs: Array) - Array: Applies a linear transformation to the inputs along multiple dimensions. Args: inputs: The nd-array to be transformed. Returns: The transformed input. ...可以观察到几个可直接复用的要点默认值写在文档中如use_bias默认True、dtype默认float32读者无需翻源码即可确定行为类型标注与字段声明一一对应docstring 里的每个Attributes条目都对应一个带类型注解的类字段__call__单独标注Args:与Returns:与类级Attributes严格区分复杂语义举例说明如axis的(-2, -1)会作用在最后两维这类信息只有写清楚读者才能正确使用。五、Notebook 与多格式文档的维护约定除 rst 与 docstring 外Flax 文档还包含大量 Jupyter Notebook如 nnx_basics.ipynb。仓库采用jupytext 双份同步策略每个 Notebook 同时维护.ipynb与.mdMyST 格式两个版本前者可直接在 Jupyter/Colab 中打开执行后者便于在版本控制中做 diff 审查。相关细节可参阅 docs_nnx/contributing.md 中的 Updating Jupyter Notebooks 一节核心操作包括# 同步 .ipynb 与 .md jupytext --sync path/to/the/file.ipynb jupytext --sync path/to/the/file.md # 为新建 Notebook 设置双格式 jupytext --set-formats ipynb,md:myst path/to/the/notebook.ipynb在文档正文中Notebook 代码单元格若抛错会导致构建失败如果错误是故意的需要给单元格加上raises-exceptions元数据或在代码中捕获异常。六、从 README 到仓库的完整证据链为了便于读者在仓库中进一步核验这里汇总本文涉及的关键文件及其作用仓库路径作用docs_nnx/README.md文档构建、doctest、docstring 规范的总入口docs_nnx/Makefilemake html/make doctest等构建入口docs_nnx/conf.pySphinx 构建配置扩展、主题、Notebook 执行策略、doctest 全局环境docs_nnx/conf_sphinx_patch.py为 autosummary 注入annotations变量的 Sphinx 补丁docs_nnx/_ext/flax_module.py自定义flax_module指令自动渲染模块类文档docs_nnx/_templates/autosummary/flax_module.rst类文档渲染模板docs_nnx/index.rst文档站首页与全局 toctree 导航pyproject.toml声明docs可选依赖组、doctest 选项flax/linen/linear.pyDenseGeneraldocstring 规范示例tests/run_all_tests.sh仓库整体测试入口含文档相关测试七、常见问题与排错提示make html提示找不到sphinx-build说明.[docs]依赖未安装成功重新执行uv pip install -e .[docs]并确认sphinx6.2.1已按 pyproject.toml 锁定版本安装Notebook 构建报错检查该 Notebook 是否在 conf.py 的nb_execution_excludepatterns排除列表中不在列表中的 Notebook 一旦 cell 抛错nb_execution_raise_on_error True会让构建直接失败doctest 输出比对失败确认输出与全局环境中jax/jnp/nnx的默认精度、日志输出一致必要时在 pyproject.toml 已有的NUMBER、ELLIPSIS选项之外按需调整API 参考页缺少方法检查对应的.. flax_module::指令的:module:与:class:参数是否正确以及类成员的注解是否被 flax_module.rst 模板按规则过滤。通过上述流程你可以完整地把 Flax NNX 的官方文档在本地构建出来、验证其中所有嵌入代码的正确性并按照 Flax 社区标准为新的模块编写能够自动生成 API 文档的 docstring——这套文档即测试、docstring 即文档的工作流正是 Flax 保持文档与代码长期同步的核心机制。【免费下载链接】flaxFlax is a neural network library for JAX that is designed for flexibility.项目地址: https://gitcode.com/GitHub_Trending/fl/flax创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Flax 文档构建与写作实战指南：Sphinx、doctest 与 docstring 规范全解析
Flax 文档构建与写作实战指南Sphinx、doctest 与 docstring 规范全解析【免费下载链接】flaxFlax is a neural network library for JAX that is designed for flexibility.项目地址: https://gitcode.com/GitHub_Trending/fl/flaxFlax 是一个面向 JAX 的神经网络库其核心是新一代NNXAPI使用 Python 引用语义表达模型。本指南以仓库中 docs_nnx/README.md 为主线系统讲解 Flax NNX 文档体系的结构、本地构建流程Sphinx Makefile、嵌入代码测试机制doctest以及 docstring 编写规范并辅以仓库源码conf.py、Makefile、flax_module.py 等进行纵深剖析。读完本文你将能独立在本地构建 Flax 文档、运行嵌入代码测试并写出符合 Flax 社区标准、可被自动测试与自动生成 API 参考的 docstring。一、Flax 文档在哪里Flax 的官方文档托管于在线文档站而当前仓库中维护着两份完整的文档源码目录docs/面向旧版Flax LinenAPI 的文档docs_nnx/面向新一代Flax NNXAPI 的文档是本指南的核心对象。从 docs_nnx/conf.py 的站点公告配置可以看到当前文档站专门标注了 This site covers the new Flax NNX API并引导读者前往旧版 Linen API 站点说明 NNX 文档站是 Flax 文档当前的主线。docs_nnx 目录内的内容非常丰富主要包括入门教程nnx_basics.md、mnist_tutorial.md、key_concepts.md深入指南guides/包含 transforms、filters、checkpointing、data_loaders 等主题、migrating/Linen 到 NNX 迁移指南设计文档与 FLIPflip/ 目录存放 Flax 特性提案Feature Lifecycle/Improvement ProposalsAPI 参考api_reference/ 以flax.nnx模块为单位组织的 rst 文件示例examples/minigpt、vit_training、gemma 等 Notebook导航与目录文件index.rst、guides_basic.rst、guides_advanced.rst、nnx_glossary.rst、why.rst。从 index.rst 的隐藏 toctree 可以看到文档站的完整导航结构它决定了在线文档的目录组织顺序。二、在本地构建 Flax 文档README.md 给出了完整的本地构建流程下面结合仓库实际配置逐步展开。2.1 安装依赖克隆仓库后在flax主目录下用uv安装带文档依赖的可编辑版本git clone 仓库地址 cd flax uv pip install -e .[docs].[docs]对应 pyproject.toml 中声明的docs可选依赖组它锁定了文档构建所需的关键工具版本包括sphinx6.2.1文档构建引擎sphinx-book-themeHTML 主题对应 conf.py 中的html_thememyst_nb支持 Markdown 与 Jupyter Notebook.ipynb的 MyST 解析器jupytext1.13.8用于 Notebook 与 Markdown 双份文件的同步sphinx-design提供 index 页面中的卡片式布局card/grid 指令。从 pyproject.toml 还可以看到 Flax 主包本身的运行时依赖jax0.10.0、optax、orbax-checkpoint、treescope等构建文档前需要确保这些依赖就绪。2.2 执行构建在docs_nnx目录下运行make html该命令由 docs_nnx/Makefile 定义它是最小化的 Sphinx MakefileSPHINXBUILD默认指向sphinx-buildSOURCEDIR .表示以docs_nnx目录为源码根BUILDDIR _build指定输出目录。构建成功后会出现提示The HTML pages are in _build/html.产物位于docs_nnx/_build/html可以用浏览器打开预览。需要说明的是README.md 中预览 docs/_build/html的表述对应的是旧目录约定在本仓库中构建输出实际位于docs_nnx/_build/html。2.3 文件变更时自动重建可选如果需要边改边看效果可以安装entr工具它能在文件变化时触发命令然后运行find ../ ! -regex .*/[\.|\_].* | entr -s make html该命令会监控docs_nnx上级目录即仓库根中所有非隐藏文件一旦有变更便自动重新执行make html。注意由于构建输出_build目录以下划线开头会被正则排除避免触发无限重建。2.4 构建配置与笔记本执行策略构建行为由 docs_nnx/conf.py 全面控制几个值得注意的配置点源文件后缀顺序conf.py 中source_suffix [.rst, .ipynb, .md]特意把.ipynb排在.md之前。注释说明这是因为每个 Notebook 都有.md与.ipynb双份拷贝未执行的 Notebook 输出只存在于.ipynb中因此必须优先转换.ipynbNotebook 执行策略conf.py 通过环境变量NB_EXECUTION_MODE控制默认off即构建时不执行 Notebooknb_execution_timeout 100设定单 cell 超时nb_execution_excludepatterns列出了需要排除执行的 Notebook如会超时的mnist_tutorial.ipynb、依赖旧版 flax 的transfer_learning.ipynb等且nb_execution_raise_on_error True一旦执行出错会直接让构建失败从而让 CI 及时捕获问题环境变量conf.py 在构建时设置os.environ[FLAX_DOC_BUILD] true供库内代码判断当前是否处于文档构建上下文自定义扩展conf.py 注册了codediff与flax_module两个仓库自带扩展路径分别为 docs_nnx/_ext/codediff.py 与 docs_nnx/_ext/flax_module.py通过sys.path.append(os.path.abspath(./_ext))加入搜索路径。2.5 自定义扩展与 API 参考生成Flax 的 API 参考不是手写的而是通过 Sphinx autosummary 自动从源码 docstring 生成的flax_module 指令docs_nnx/_ext/flax_module.py 提供.. flax_module::指令用法为.. flax_module:: :module: flax.linen :class: Dense它通过importlib导入指定模块、取出类对象调用generate_autosummary_content渲染模板从而把类的 docstring、方法与属性自动展开成文档页面Sphinx 补丁docs_nnx/conf_sphinx_patch.py 对 Sphinx 的generate_autosummary_content打了补丁核心只加了一行ns[annotations] list(getattr(obj, __annotations__, {}).keys())补丁注释conf_sphinx_patch.py说明这是为了让 autosummary 提供annotations变量从而在模板中把类注解属性从方法列表中排除模板docs_nnx/_templates/autosummary/flax_module.rst 定义了类的文档渲染模板自动输出automethod:: __call__并遍历方法列表过滤掉__init__、setup以及作为注解的属性。这意味着你在源码 docstring 里写的每一行注释都会直接进入在线 API 文档这也正是下文 docstring 规范如此重要的原因。三、运行嵌入代码测试doctest3.1 doctest 机制Flax 文档中的嵌入代码示例不是摆设而是会作为测试在 CI 中真实运行。其机制基于 Python 标准库的doctest与 Sphinx 的sphinx.ext.doctest扩展在 conf.py 中启用。在docs_nnx目录下运行make doctest即可在本地执行所有文档中的 doctest 块。3.2 doctest 全局环境conf.py 为 doctest 准备了全局初始化脚本doctest_global_setupimport jax jax.config.update(jax_num_cpu_devices, 8) import jax.numpy as jnp from flax import nnx这保证了所有 doctest 块默认就可以直接使用jax、jnp、nnx并且模拟 8 个 CPU 设备便于测试 SPMD/并行相关示例。此外脚本还通过自定义logging.Formatter过滤掉 absl 日志中SaveArgs.aggregate is deprecated等噪音消息避免它们破坏 doctest 的输出比对。同时 conf.py 设置了doctest_default_flags doctest.NORMALIZE_WHITESPACE允许忽略空白差异pyproject.toml 中doctest_optionflags [NUMBER, ELLIPSIS]进一步放宽了对浮点精度和省略号输出的要求。3.3 在文档中编写 doctest在 reStructuredText 或 docstring 中使用::引入代码块并缩进即可被 doctest 捕获Example code之前的说明文字可以随意替换只要满足冒号加换行、代码缩进的格式即可Example code:: def sum(a, b): return a b sum(0, 1)在 docstring 中的写法类似双引号包裹注释形式配合 Sphinx 的代码高亮# Example code:: # # def sum(a, b): # return a b # # sum(0, 1)四、编写高质量 docstringFlax 社区规范README.md 强调docstring 应当信息充分。对于实现新功能的Module仅提供一行解释是不够的We prefer to err on the side of too much documentation than too little并且强烈鼓励在 docstring 中加入示例代码让用户直接看到用法。由于 API 参考页面由 docstring 自动生成docstring 质量直接决定文档质量。4.1 使用 code font写行内代码时使用双反引号例如 str。参数名以及True、None等对象、字符串字面量通常都应放入行内代码This returns a str object.4.2 创建交叉引用cross-reference使用 Sphinx 的引用语法可以链接到其他类、函数与方法其中obj_type取class、func或meth之一# 第一种方法 # obj_type:path_to_obj # 第二种方法带显示名称 # :obj_type:description path_to_obj当目标路径很长时推荐使用第二种方法。官方示例# 引用 flax.linen.Module 类 :class:flax.linen.Module # 引用本地函数 my_func :func:my_func # 引用 Module.apply() 方法 :meth:Module.apply() flax.linen.Module.apply创建超链接的语法如下注意结尾是双下划线Link to Google http://www.google.com__4.3 参数与属性标注规范类属性使用Attributes:标签方法参数使用Args:标签所有属性和参数都必须标注类型。仓库中的DenseGeneral定义于 flax/linen/linear.py是这一规范的典型范例其 docstring 完整展示了每个字段的含义、类型与默认值class DenseGeneral(Module): A linear transformation with flexible axes. Attributes: features: int or tuple with number of output features. axis: int or tuple with axes to apply the transformation on. For instance, (-2, -1) will apply the transformation to the last two axes. batch_dims: tuple with batch axes. use_bias: whether to add a bias to the output (default: True). dtype: the dtype of the computation (default: float32). kernel_init: initializer function for the weight matrix. bias_init: initializer function for the bias. precision: numerical precision of the computation see jax.lax.Precision for details. features: Union[int, Iterable[int]] axis: Union[int, Iterable[int]] -1 batch_dims: Iterable[int] () use_bias: bool True dtype: Dtype jnp.float32 kernel_init: Callable[[PRNGKey, Shape, Dtype], Array] default_kernel_init bias_init: Callable[[PRNGKey, Shape, Dtype], Array] zeros precision: Any None compact def __call__(self, inputs: Array) - Array: Applies a linear transformation to the inputs along multiple dimensions. Args: inputs: The nd-array to be transformed. Returns: The transformed input. ...可以观察到几个可直接复用的要点默认值写在文档中如use_bias默认True、dtype默认float32读者无需翻源码即可确定行为类型标注与字段声明一一对应docstring 里的每个Attributes条目都对应一个带类型注解的类字段__call__单独标注Args:与Returns:与类级Attributes严格区分复杂语义举例说明如axis的(-2, -1)会作用在最后两维这类信息只有写清楚读者才能正确使用。五、Notebook 与多格式文档的维护约定除 rst 与 docstring 外Flax 文档还包含大量 Jupyter Notebook如 nnx_basics.ipynb。仓库采用jupytext 双份同步策略每个 Notebook 同时维护.ipynb与.mdMyST 格式两个版本前者可直接在 Jupyter/Colab 中打开执行后者便于在版本控制中做 diff 审查。相关细节可参阅 docs_nnx/contributing.md 中的 Updating Jupyter Notebooks 一节核心操作包括# 同步 .ipynb 与 .md jupytext --sync path/to/the/file.ipynb jupytext --sync path/to/the/file.md # 为新建 Notebook 设置双格式 jupytext --set-formats ipynb,md:myst path/to/the/notebook.ipynb在文档正文中Notebook 代码单元格若抛错会导致构建失败如果错误是故意的需要给单元格加上raises-exceptions元数据或在代码中捕获异常。六、从 README 到仓库的完整证据链为了便于读者在仓库中进一步核验这里汇总本文涉及的关键文件及其作用仓库路径作用docs_nnx/README.md文档构建、doctest、docstring 规范的总入口docs_nnx/Makefilemake html/make doctest等构建入口docs_nnx/conf.pySphinx 构建配置扩展、主题、Notebook 执行策略、doctest 全局环境docs_nnx/conf_sphinx_patch.py为 autosummary 注入annotations变量的 Sphinx 补丁docs_nnx/_ext/flax_module.py自定义flax_module指令自动渲染模块类文档docs_nnx/_templates/autosummary/flax_module.rst类文档渲染模板docs_nnx/index.rst文档站首页与全局 toctree 导航pyproject.toml声明docs可选依赖组、doctest 选项flax/linen/linear.pyDenseGeneraldocstring 规范示例tests/run_all_tests.sh仓库整体测试入口含文档相关测试七、常见问题与排错提示make html提示找不到sphinx-build说明.[docs]依赖未安装成功重新执行uv pip install -e .[docs]并确认sphinx6.2.1已按 pyproject.toml 锁定版本安装Notebook 构建报错检查该 Notebook 是否在 conf.py 的nb_execution_excludepatterns排除列表中不在列表中的 Notebook 一旦 cell 抛错nb_execution_raise_on_error True会让构建直接失败doctest 输出比对失败确认输出与全局环境中jax/jnp/nnx的默认精度、日志输出一致必要时在 pyproject.toml 已有的NUMBER、ELLIPSIS选项之外按需调整API 参考页缺少方法检查对应的.. flax_module::指令的:module:与:class:参数是否正确以及类成员的注解是否被 flax_module.rst 模板按规则过滤。通过上述流程你可以完整地把 Flax NNX 的官方文档在本地构建出来、验证其中所有嵌入代码的正确性并按照 Flax 社区标准为新的模块编写能够自动生成 API 文档的 docstring——这套文档即测试、docstring 即文档的工作流正是 Flax 保持文档与代码长期同步的核心机制。【免费下载链接】flaxFlax is a neural network library for JAX that is designed for flexibility.项目地址: https://gitcode.com/GitHub_Trending/fl/flax创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
