企业官网建设流程全解析

TensorFlow Models 仓库文档生成脚本解析：如何用 tensorflow_docs 构建 tfm 与 Orbit 的 API 参考页

【免费下载链接】modelsModels and examples built with TensorFlow项目地址: https://gitcode.com/GitHub_Trending/mode/models

本文基于 official/utils/docs/README.md 及其同目录下的两个生成脚本，讲解 TensorFlow Models 仓库中 API 参考文档（即 tensorflow.org 上tfm与Orbit的 API reference 页面）的生成机制：如何安装tensorflow_docs、如何运行build_tfm_api_docs.py与build_orbit_api_docs.py、各命令行参数的含义，以及脚本内部通过DocGenerator、doc_controls等机制过滤和定制文档页面的底层实现。读完本文，你可以自行在本机复现 API 文档生成流程，并理解仓库中"隐藏 Keras 基类方法""为实验工厂生成选项表格"等文档定制技巧。

文档生成脚本的定位与运行前提

official/utils/docs/ 目录中的脚本用于为 TensorFlow Models（official目录下的tensorflow_models库与orbit库）生成 api-reference 页面，供发布到 tensorflow.org。official/README.md 中也印证了这一点：最新稳定版本的 API 文档会发布到 tensorflow.org 的tfm路径下。

该目录包含以下文件：

• README.md：使用说明（即本文主体依据的文档）；
• build_tfm_api_docs.py：为tensorflow_models（简称tfm，"TensorFlow Modeling Library"）生成 API 文档；
• build_orbit_api_docs.py：为orbit包生成 API 文档；
• __init__.py：仅含许可声明的空包文件。

运行前提来自 README 的明确说明：脚本依赖tensorflow_docs包，需要从 GitHub 直接安装（而非 PyPI 发行版），因为 API 生成器接口迭代较快：

$> pip install -U git+https://github.com/tensorflow/docs $> python build_all_api_docs.py --output_dir=/tmp/tfm_docs

需要注意一个仓库事实：README 中给出的示例命令是build_all_api_docs.py，但从当前仓库目录结构看，该文件并不存在于official/utils/docs/下，实际可用的是上述两个分开的脚本；且 build_tfm_api_docs.py 文件头 docstring 中的示例也写的是build_nlp_api_docs.py，同样属于历史遗留的过时文件名。可以推断该 README 早于脚本重命名。实际可复制运行的命令应以真实存在的文件名为准（见下文）。此外，两个脚本都直接import tensorflow as tf, tf_keras，因此运行环境必须先安装 TensorFlow（含 tf_keras）。

build_tfm_api_docs.py：为 tfm 库生成 API 文档

命令行参数（absl flags）

脚本使用 absl 框架定义命令行参数（见 build_tfm_api_docs.py）：

入口逻辑（main）通过app.run(main)启动，并禁止传入多余的位置参数。实际运行命令为：

$> pip install -U git+https://github.com/tensorflow/docs $> python build_tfm_api_docs.py --output_dir=/tmp/api_docs

核心流程：gen_api_docs

gen_api_docs 是真正的生成入口，内部按顺序完成几件事：

1. 隐藏 Keras 基类的继承成员：调用hide_module_model_and_layer_methods()（L96-L129）。该函数遍历tf.Module、tf_keras.Model和tf_keras.layers.Layer三类基类自身的属性，对其中的方法/属性调用doc_controls.do_not_doc_in_subclasses(obj)，使生成文档时自动排除从 Keras 基类继承来的大量通用方法（如train_step、set_weights等），只保留两个例外：

   • __init__始终保留文档；
   • call始终保留文档（对复杂层而言call常携带关键信息），并且会移除call上的_FOR_SUBCLASS_IMPLEMENTERS标记，避免被误标为"由子类实现者编写"。 对property/staticmethod/classmethod会先解包到真正的函数对象再打标记，并容忍AttributeError（基类中并非所有成员都是函数）。

2. 删除不再需要的 API：del tfm.nlp.layers.MultiHeadAttention与del tfm.nlp.layers.EinsumDense，直接让这两个符号从文档树中消失。

3. 为实验工厂注册自定义页面：doc_controls.set_custom_page_builder_cls(tfm.core.exp_factory.get_exp_config, ExpFactoryInfo)。exp_factory.get_exp_config 负责按exp_name从注册表_REGISTERED_CONFIGS中查回ExperimentConfig，是各模型实验配置的统一入口。

4. 构造 DocGenerator 并构建：

doc_generator = generate_lib.DocGenerator( root_title=project_full_name, py_modules=[(project_short_name, tfm)], base_dir=[tfm_base_dir, official_base_dir], code_url_prefix=[code_url_prefix, official_url_prefix], search_hints=search_hints, site_path=site_path, callbacks=[custom_filter], ) doc_generator.build(output_dir)

其中有一个值得注意的细节：tfm（由 tensorflow_models/__init__.py 重导出official下的core、nlp、vision、uplift、modeling等模块）中的许多子模块实际定义在official包目录内，而不在tensorflow_models/目录下。脚本因此定位tfm.vision.layers.__file__的父路径链，找到名字为official的目录作为第二个base_dir，并据此把code_url_prefix截断到tensorflow_models之前再拼上official，得到official_url_prefix。这样"源码链接"才能正确指向official/...下的真实文件路径。

5. 内容过滤回调 custom_filter（L132-L137）：

def custom_filter(path, parent, children): if len(path) <= 2: # 顶层 tfm.vision 等包的直接成员不做过滤 return children return public_api.explicit_package_contents_filter(path, parent, children)

public_api.explicit_package_contents_filter是 tensorflow_docs 提供的过滤器：只保留包__init__.py中显式导入（import/from ... import）的公开名称，避免把私有实现细节泄漏进公开 API 页。custom_filter放宽了最顶层两级，保证tfm.vision等顶层包的直接成员完整可见。

ExpFactoryInfo：为 get_exp_config 生成"可用实验名"表格

ExpFactoryInfo 继承自function_page.FunctionPageInfo，是注册到get_exp_config页面上的定制页构建器。它在默认的函数文档之后追加一张 HTML 表格，动态列出exp_name的所有允许取值：

• 遍历tfm.core.exp_factory._REGISTERED_CONFIGS（注册表定义于 official/core/exp_factory.py），按名称排序；
• 每个工厂函数若能被api_tree解析到，则生成指向其 API 页面的链接（reference_resolver.python_link）；解析不到时退化为源码小链接（base_page.small_source_link）；
• 描述列取工厂函数 docstring 的第一行。

也就是说，API 文档页上"哪些实验配置可用"这张表是运行时从注册表现场生成的，而不是手写维护的——每当有新实验通过@register_config_factory注册，文档重建后表格自动包含它。源码中还特意保留了表格前的两空格缩进，注释说明这是为了防止站点 markdown 解析器切换到 HTML 模式而破坏排版。

build_orbit_api_docs.py：为 Orbit 包生成 API 文档

build_orbit_api_docs.py 是 tfm 脚本的简化版，结构几乎一致，差异点在于：

• 文档根标题为Orbit（PROJECT_SHORT_NAME = 'orbit'，PROJECT_FULL_NAME = 'Orbit'，见 L47-L48），py_modules=[('orbit', orbit)]；
• code_url_prefix默认指向https://github.com/tensorflow/models/blob/master/orbit；
• 同样实现了hide_module_model_and_layer_methods()（L51-L84），因为 Orbit 的 Controller/Runner 也大量继承 KerasModel；
• 没有ExpFactoryInfo定制页，过滤回调直接使用public_api.explicit_package_contents_filter（L97），不做顶层放宽。

运行命令（见文件头 L15-L21）：

$> pip install -U git+https://github.com/tensorflow/docs $> python build_orbit_api_docs.py --output_dir=/tmp/api_docs

生成的产物是output_dir下的一组 Markdown 页面加_toc.yaml目录文件（由site_path决定路径前缀），可直接交给 tensorflow.org 的文档站点流程渲染。

小结与适用前提

• 仓库中实际的生成入口是 build_tfm_api_docs.py 与 build_orbit_api_docs.py 两个脚本，README 里的build_all_api_docs.py是过时文件名；
• 两个脚本的共同模式：安装 git 版tensorflow_docs→ 用DocGenerator以包名为根解析公共 API → 用doc_controls.do_not_doc_in_subclasses隐藏 Keras 基类继承成员 → 用explicit_package_contents_filter只保留显式导入的公开符号 → 按site_path输出_toc.yaml与页面；
• 运行前提是装有 TensorFlow（含tf_keras）的 Python 环境，且official与tensorflow_models包需可从当前工作目录导入（本仓库根目录下即可）。
• 本文所有实现描述均基于当前仓库文件，如需进一步阅读，可对照 official/core/exp_factory.py 的注册表实现与 official/README.md 中的文档发布说明。

【免费下载链接】modelsModels and examples built with TensorFlow项目地址: https://gitcode.com/GitHub_Trending/mode/models