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` 文件开始创建新示例

将 ipynb 文件保存到本地磁盘。
通过运行以下命令将文件转换为 tutobook：（假设您在 scripts/ 目录中）

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

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

打开它，填写标头，并进行一般编辑，使其看起来美观。

注意，转换脚本在尝试缩短行时可能会出错。请确保仔细校对生成的 .py 文件。或者，确保您的初始行长度合理（<90 个字符），这样脚本就不必缩短它们。

运行 python autogen.py add_example vision/script_name。这将生成您示例的 ipynb 和 markdown 渲染，在 examples/vision/ipynb、examples/vision/md 和 examples/vision/img 中创建文件。请勿手动修改这些文件；只应手动编辑原始 Python 脚本。
提交一个 PR，添加 examples/vision/script_name.py（只添加 .py，不添加生成的文件）。获取审核和批准。
PR 获得批准后，将 add_example 命令创建的文件添加到 PR 中。然后我们将合并 PR。

从 Python 脚本开始创建新示例

使用 black 格式化脚本：black script_name.py
添加 tutobook 标头
将脚本放在 examples/ 的相关子文件夹中（例如 examples/vision/script_name）
运行 python autogen.py add_example vision/script_name。这将生成您示例的 ipynb 和 markdown 渲染，在 examples/vision/ipynb、examples/vision/md 和 examples/vision/img 中创建文件。请勿手动修改这些文件；只应手动编辑原始 Python 脚本。
提交一个 PR，添加 examples/vision/script_name.py（只添加 .py，不添加生成的文件）。获取审核和批准。
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

keras-io