为 TensorFlow 文档做贡献

TensorFlow 欢迎文档贡献 - 如果您改进文档,等同于改进 TensorFlow 库本身。tensorflow.org 上的文档分为以下几类:

某些 TensorFlow 项目将文档源文件保存在单独仓库中的代码旁,通常位于 docs/ 目录中。请参阅项目的 CONTRIBUTING.md 文件或联系维护者以做贡献。

参与 TensorFlow 文档社区:

API 参考

有关详细信息,请使用 TensorFlow API 文档贡献者指南。这向您展示了如何找到源文件并编辑符号的 docstring。tensorflow.org 上的许多 API 参考页面都包含指向定义符号的源文件的链接。Docstring 支持 Markdown 并且(绝大多数时候)都能使用任意 Markdown 预览程序进行浏览。

版本和分支

本网站的 API 参考版本默认为最新的稳定二进制文件,与通过 pip install tensorflow 安装的软件包匹配。

默认的 TensorFlow 软件包根据 tensorflow/tensorflow 主仓库中的稳定分支 rX.x 构建。参考文档由 PythonC++Java 源代码中的代码注释与 docstring 生成。

以前版本的 TensorFlow 文档在 TensorFlow Docs 仓库中以 rX.x 分支形式提供。在发布新版本时会添加这些分支。

构建 API 文档

注:编辑或预览 API docstring 不需要此步骤,只需生成 tensorflow.org 上使用的 HTML。

Python 参考

tensorflow_docs 软件包中包含 Python API 参考文档的生成器。要安装,请运行以下代码:

pip install git+https://github.com/tensorflow/docs

要生成 TensorFlow 2 参考文档,请使用 tensorflow/tools/docs/generate2.py 脚本:

git clone https://github.com/tensorflow/tensorflow tensorflow
cd tensorflow/tensorflow/tools/docs
pip install tensorflow
python generate2.py --output_dir=/tmp/out

注:此脚本使用已安装的 TensorFlow 软件包来生成文档,并且仅适用于 TensorFlow 2.x。

叙述文档

TensorFlow 指南教程作为 Markdown 文件和交互式 Jupyter 笔记本编写。可以使用 Google Colaboratory 在您的浏览器中运行笔记本。tensorflow.org 上的叙述文档根据 tensorflow/docsmaster 分支构建。旧版本存储在在 GitHub 仓库下的 rX.x 版本分支中。

简单变更

Markdown 文件进行简单文档更新的最简单方法是使用 GitHub 的 Web 文件编辑器。浏览 tensorflow/docs 仓库以找到与 tensorflow.org 网址结构大致对应的 Markdown。在文件视图的右上角,点击铅笔图标 打开文件编辑器。编辑文件,然后提交新的拉取请求。

设置本地 Git 仓库

对于多文件编辑或更复杂的更新,最好使用本地 Git 工作流创建拉取请求。

注:Git 是用于跟踪源代码变更的开源版本控制系统 (VCS)。GitHub是一种在线服务,提供可与 Git 配合使用的协作工具。请参阅 GitHub 帮助来设置您的 GitHub 帐号并开始使用。

只有在第一次设置本地项目时才需要以下 Git 步骤。

复刻 tensorflow/docs 仓库

tensorflow/docs Github 页面中,点击 Fork 按钮 在您的 GitHub 帐号下创建您自己的仓库副本。复刻后,您需要保持您的仓库副本与上游 TensorFlow 仓库同步。

克隆您的仓库

您的远程 username/docs 仓库的副本下载到本地计算机。这是您之后进行更改的工作目录:

git clone git@github.com:<var>username</var>/docs
cd ./docs

添加上游仓库以保持最新(可选)

要使本地存储库与 tensorflow/docs 保持同步,请添加一个上游仓库来下载最新变更。

注:确保在开始贡献之前更新您的本地仓库。定期向上游同步会降低您在提交拉取请求时产生合并冲突的可能性。

添加远程仓库:

<code class="devsite-terminal">git remote add upstream git@github.com:tensorflow/docs.git</code>

# View remote repos
<code class="devsite-terminal">git remote -v</code>
origin    git@github.com:<var>username</var>/docs.git (fetch)
origin    git@github.com:<var>username</var>/docs.git (push)
upstream  git@github.com:tensorflow/docs.git (fetch)
upstream  git@github.com:tensorflow/docs.git (push)

更新:

<code class="devsite-terminal">git checkout master</code>
<code class="devsite-terminal">git pull upstream master</code>

<code class="devsite-terminal">git push</code>  # Push changes to your GitHub account (defaults to origin)

GitHub 工作流

1. 创建一个新分支

tensorflow/docs 更新您的仓库后,从本地 master 分支创建一个新分支:

<code class="devsite-terminal">git checkout -b <var>feature-name</var></code>

<code class="devsite-terminal">git branch</code>  # List local branches
  master

* <var>feature-name</var>

2. 进行更改

在您喜欢的编辑器中编辑文件,并请遵守 TensorFlow 文档风格指南

提交文件变更:

# View changes
<code class="devsite-terminal">git status</code>  # See which files have changed
<code class="devsite-terminal">git diff</code>    # See changes within files

<code class="devsite-terminal">git add <var>path/to/file.md</var></code>
<code class="devsite-terminal">git commit -m "Your meaningful commit message for the change."</code>

根据需要添加更多提交。

3. 创建拉取请求

将本地分支上传到您的远程 GitHub 仓库 (github.com/username/docs):

git push

推送完成后,消息可能会显示一个网址,以自动向上游仓库提交拉取请求。如果没有,请转到 tensorflow/docs 仓库或者您自己的仓库,GitHub 将提示您创建拉取请求。

4. 审查

维护者和其他贡献者将审查您的拉取请求。请参与讨论并根据要求进行修改。当您的请求获得批准后,它将被合并到上游 TensorFlow 文档仓库中。

成功:您的变更已被 TensorFlow 文档接受。

从 GitHub 仓库更新 tensorflow.org 是一个单独的步骤。通常情况下,多个变更将一起处理,并定期上传至网站。

交互式笔记本

虽然可以使用 GitHub 的 Web 文件编辑器编辑笔记本 JSON 文件,但不推荐使用,因为格式错误的 JSON 可能会损坏文件。确保先测试笔记本,然后再提交拉取请求。

Google Colaboratory 是一个托管笔记本环境,可以轻松编辑和运行笔记本文档。GitHub 中的笔记本通过将路径传递给 Colab 网址加载到 Google Colab 中,例如,位于 GitHub 中以下位置的笔记本: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras/basic_classification.ipynb
可以通过以下网址加载到 Google Colab 中:https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/basic_classification.ipynb

有一个 Open in Colab Chrome 扩展程序,可以在 GitHub 上浏览笔记本时执行此网址替换。这在仓库复刻中打开笔记本时非常有用,因为顶部按钮始终链接到 TensorFlow Docs 的 master 分支。

笔记本格式设置

借助笔记本格式设置工具,可使 Jupyter 笔记本源差异一直并更易于审查。由于笔记本写作在文件输出、缩进、元数据和其他非指定字段方面不同,nbfmt 使用偏好 TensorFlow 文档 Colab 工作流的默认设置。要设置笔记本格式,请安装 TensorFlow 文档笔记本工具并运行 nbfmt 工具:

# Install the tensorflow-docs package:
$ python3 -m pip install -U [--user] git+https://github.com/tensorflow/docs

$ python3 -m tensorflow_docs.tools.nbfmt [options] notebook.ipynb [...]

对于 TensorFlow 文档项目,将执行和测试没有输出单元的笔记本;而带有保存输出单元的笔记本将按原样发布。nbfmt 遵从笔记本状态并使用 --remove_outputs 选项显式移除输出单元。

要创建新笔记本,请复制并编辑 TensorFlow 文档笔记本模板

在 Colab 中编辑

在 Google Colab 环境中,双击单元可以编辑文本块和代码块。文本单元使用 Markdown 并且应遵循 TensorFlow 文档风格指南

点击 File > Download .pynb,从 Colab 中下载笔记本文件。将此文件提交到您的本地 Git 仓库并发送拉取请求。

要创建新笔记本,请复制并编辑 TensorFlow 笔记本模板

Colab-GitHub 工作流

您可以直接 从Google Colab 编辑和更新复刻的 GitHub 仓库,而不用下载笔记本文件并使用本地 Git 工作流:

  1. 在您复制的 username/docs 仓库中,使用 GitHub Web 界面创建新分支
  2. 导航到要编辑的笔记本文件。
  3. 在 Google Colab 中打开笔记本:使用网址替换或 Open in Colab Chrome 扩展程序。
  4. 在 Colab 中编辑笔记本。
  5. 点击 File > Save a copy in GitHub... 从 Colab 中向您的仓库提交变更。保存对话框应链接到相应的仓库和分支。添加一条有意义的提交消息。
  6. 保存后,浏览到您的仓库或者 tensorflow/docs 仓库,GitHub 应提示您创建拉取请求。
  7. 维护者会审查拉取请求。

成功:您的变更已被 TensorFlow 文档接受。

翻译

TensorFlow 团队与社区和供应商合作,为 tensorflow.org 提供翻译。笔记本和其他技术内容的翻译位于 tensorflow/docs-l10n GitHub 仓库中。请通过 TensorFlow GitLocalize 项目提交拉取请求。

英文文档是事实来源,翻译应尽可能遵循这些指南。也就是说,翻译是为它们所服务的社区编写的。如果英语术语、措辞、风格或语气不能翻译成另一种语言,请使用适合读者的翻译。

语言支持由多种因素决定,包括但不限于站点指标和需求、社区支持、英语水平、受众偏好和其他指标。由于每种支持的语言都会产生成本,因此会删除未维护的语言。我们将在 TensorFlow 博客Twitter 上公布对新语言的支持。

如果您的首选语言不受支持,欢迎您为开源贡献者维护社区复刻。这些内容不会发布到 tensorflow.org。