Keras.io 文档生成器

本仓库包含用于生成 keras.io 网站的代码。

生成网站的本地副本

pip install -r requirements.txt
# 更新 Keras 版本到 3
pip install keras==3.0.2
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 代码示例以 tutobooks 的形式实现。

tutobook 是一种同时可用作笔记本、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)

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

从 ipynb 文件开始创建新示例

1. 将 ipynb 文件保存到本地磁盘。
2. 通过运行以下命令将文件转换为 tutobook： （假设您在 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。这将生成您示例的 ipynb 和 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. 添加 tutobook 标头
3. 将脚本放在 examples/ 的相关子文件夹中（例如 examples/vision/script_name）
4. 运行 python autogen.py add_example vision/script_name。这将生成您示例的 ipynb 和 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

（假设 tutobook 文件是 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