Keras.io 文档生成器

此仓库托管用于生成 keras.io 网站的代码。

生成网站的本地副本

pip install -r requirements.txt
# 更新 Keras 版本
pip install -U keras
cd scripts
python autogen.py make
python autogen.py serve

如果您有 Docker（不需要 GPU 版本的 Docker），也可以运行以下命令：

docker build -t keras-io . && docker run --rm -p 8000:8000 keras-io

首次运行时会花费一些时间，因为需要拉取镜像和依赖项，但后续运行会快得多。

另一种使用 Docker 测试的方法是通过我们的 Makefile：

make container-test

该命令将构建一个包含文档服务器的 Docker 镜像并运行它。

征集示例

您是否有兴趣提交新的示例以在 keras.io 上发布？我们非常欢迎您的贡献！请阅读下方关于添加新代码示例的信息。

我们目前对 [以下示例] 感兴趣：链接。

修复现有代码示例中的问题

修正拼写错误

如果您的修复非常简单，请同时更新示例的 .py、.md 和 .ipynb 文件，并提交一个 PR。

更复杂的修复

对于较大的修复，请仅提交包含 .py 文件的 PR，以便在代码经过审查并批准后，再更新另外两个文件。

添加新的代码示例

Keras 代码示例以 教程书 的形式实现。

教程书是一种脚本，可以同时以笔记本、Python 文件以及美观渲染的网页形式呈现。

其真实来源（用于手动编辑和版本控制）是 Python 脚本形式，但您也可以从笔记本开始，使用 nb2py 命令将其转换为教程书。

文本单元存储在 Markdown 格式的注释块中。第一行（以 """ 开头）可以选择性地包含特殊标注，例如：

• shell: 在每行前加上 ! 后执行该块。
• invisible: 不渲染该块。

脚本应以包含以下字段的头部开始：

Title: (标题)
Author: (也可以是 `Authors`，并可包含 Markdown 链接)
Date created: (日期格式为 yyyy/mm/dd)
Last modified: (日期格式为 yyyy/mm/dd)
Description: (一行文本描述)
Accelerator: (可以是 GPU、TPU 或 None)

要查看教程书的示例，您可以查看 examples/ 或 guides/ 中的任何 .py 文件。

从 ipynb 文件创建新示例

1. 将 ipynb 文件保存到本地磁盘。
2. 运行以下命令将文件转换为教程书（假设您位于 scripts/ 目录下）：

python tutobooks.py nb2py path_to_your_nb.ipynb ../examples/vision/script_name.py

这将创建文件 examples/vision/script_name.py。

3. 打开文件，填写头部信息，并进行整体编辑，使其看起来整洁美观。

请注意，转换脚本在尝试缩短行时可能会出错。请务必完整校对生成的 .py 文件。或者，您也可以一开始就保持代码行长度合理（<90 字符），这样脚本就不必对其进行缩短。

4. 运行 python autogen.py add_example vision/script_name。这将生成您示例的 IPython 笔记本和 Markdown 渲染版本，并在 examples/vision/ipynb、examples/vision/md 和 examples/vision/img 中创建文件。请勿手动修改这些文件；只有原始 Python 脚本才应被手动编辑。
5. 提交一个 PR，添加 examples/vision/script_name.py（仅 .py 文件，不包括生成的文件）。等待审查和批准。
6. 一旦 PR 被批准，将 add_example 命令生成的文件添加到 PR 中，然后我们将合并 PR。

从 Python 脚本创建新示例

1. 使用 black 格式化脚本：black script_name.py
2. 添加教程书头部。
3. 将脚本放入 examples/ 中的相关子文件夹（例如 examples/vision/script_name）。
4. 运行 python autogen.py add_example vision/script_name。这将生成您示例的 IPython 笔记本和 Markdown 渲染版本，并在 examples/vision/ipynb、examples/vision/md 和 examples/vision/img 中创建文件。请勿手动修改这些文件；只有原始 Python 脚本才应被手动编辑。
5. 提交一个 PR，添加 examples/vision/script_name.py（仅 .py 文件，不包括生成的文件）。等待审查和批准。
6. 一旦 PR 被批准，将 add_example 命令生成的文件添加到 PR 中，然后我们将合并 PR。

预览新示例

您可以通过运行以下命令，在本地预览示例的外观：

cd scripts
python autogen.py add_example vision/script_name

（假设教程书文件是 examples/vision/script_name.py。）

请注意，如果任何单元格执行时间过长，该命令将会报错。在这种情况下，请简化或加快您的代码。请记住，示例旨在演示工作流程，而非训练最先进的模型，因此它们应保持非常轻量级。

然后启动网站服务：

python autogen.py make
python autogen.py serve

访问 0.0.0.0:8000/examples 即可查看。

只读自动生成文件

以下文件夹的内容不应手动修改：

• site/*
• sources/*
• templates/examples/*
• templates/guides/*
• examples/*/md/*、examples/*/ipynb/*、examples/*/img/*
• guides/md/*、guides/ipynb/*、guides/img/*

可编辑文件

以下文件才是唯一应手动编辑的文件：

• templates/*.md，但 templates/examples/* 和 templates/guides/* 除外。
• examples/*/*.py
• guides/*.py
• theme/*
• scripts/*.py

Keras.io 文档生成器快速上手指南

本指南帮助中国开发者快速搭建 keras-io 本地环境，用于生成 Keras 官方文档网站或贡献代码示例。

环境准备

• 操作系统：Linux、macOS 或 Windows (需支持 Docker 或 Python 环境)
• 核心依赖：
  • Python 3.x
  • Git
• 可选依赖（推荐）：
  • Docker：无需 GPU 版本，使用 Docker 可避免本地环境配置冲突，一键启动服务。

安装步骤

你可以选择以下两种方式之一进行安装和运行：

方式一：使用 Docker（推荐，最简便）

如果你已安装 Docker，这是最快的方式。首次运行会拉取镜像和依赖，耗时稍长，后续运行将非常迅速。

docker build -t keras-io . && docker run --rm -p 8000:8000 keras-io

或者使用 Makefile 进行测试：

make container-test

方式二：本地 Python 环境

如果你希望在本地直接运行，请执行以下步骤：

1. 安装依赖：

   pip install -r requirements.txt
   

   国内加速建议：如果下载缓慢，可使用清华源或阿里源： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 更新 Keras 版本：

   pip install -U keras
   

   国内加速建议： pip install -U keras -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 进入脚本目录并生成/启动服务：

   cd scripts
   python autogen.py make
   python autogen.py serve
   

基本使用

成功启动后，即可在浏览器中访问本地生成的文档网站。

1. 访问地址： 打开浏览器访问 http://0.0.0.0:8000 (或 http://localhost:8000)。

2. 查看示例： 导航至 http://0.0.0.0:8000/examples 查看代码示例页面。

3. 添加新示例预览（开发者专用）： 如果你正在开发新的 Tutobook 示例（例如位于 examples/vision/script_name.py），可运行以下命令生成对应的 .ipynb 和 Markdown 文件并进行本地预览：

   cd scripts
   # 将 vision/script_name 替换为你的实际路径
   python autogen.py add_example vision/script_name
   
   # 重新构建并启动服务
   python autogen.py make
   python autogen.py serve
   

   注意：如果示例代码执行时间过长，上述命令会报错。请确保示例代码轻量级，仅用于演示工作流，而非训练大型模型。

4. 重要提示：

   • 唯一源码：所有示例的“事实来源”是 .py 文件。请勿手动修改自动生成的 .md、.ipynb 或 site/* 目录下的文件。
   • 提交规范：提交 PR 时，初期仅需提交 .py 文件；待代码审核通过后，再补充由 add_example 命令生成的其他文件。