TensorFlow欢迎文档贡献 - 如果您改进了文档,等同于改进TensorFlow库本身。 tensorflow.org上的文档分为以下几类:
- API 文档 —API 文档 经由 TensorFlow 源代码中的文档字符串(docstring)生成.
- 叙述文档 —这部分内容为教程、 指南以及其他不属于TensorFlow代码的内容. 这部分代码位于GitHub的 tensorflow/docs 仓库(repository)中.
- 社区翻译 —这些是经由社区翻译的指南和教程。他们都被存放在 tensorflow/docs 仓库(repository)中.
一些 TensorFlow 项目 将文档源文件保存在单独的存储库中,通常位于docs/
目录中。 请参阅项目的CONTRIBUTING.md
文件或联系维护者以参与。
参与到TensorFlow文档社区的方式有:
- 关注GitHub中的 tensorflow/docs 仓库(repository).
- 订阅 docs@tensorflow.org.
API 文档
如果想更新API文档,找到其对应的 源文件 并编辑相应的 文档字符串(docstring). tensorflow.org上的许多API 引用的页面都包含了指向源文件定义位置的链接。 文档字符串支持 Markdown格式 并且(绝大多数时候)都能使用 Markdown 预览器 进行浏览.
有关参考文档质量以及如何参与文档冲刺和社区,请参阅 TensorFlow 2.0 API文档建议。
版本(Versions) 和 分支(Branches)
本网站的 API 文档
版本默认为最新的稳定二进制文件—即与通过pip install tensorflow
安装的版本所匹配.
默认的TensorFlow 包是根据tensorflow/tensorflow仓库(repository)中的稳定分支rX.x
所构建的。文档则是由
Python、
C++与
Java代码中的注释与文档字符串所生成。
以前版本的TensorFlow文档在TensorFlow Docs 仓库(repository)中以rX.x 分支 的形式提供。在发布新版本时会添加这些分支。
构建API文档
注意:编辑或预览API文档字符串不需要此步骤,只需生成tensorflow.org上使用的HTML。
Python 文档
tensorflow_docs
包中包含Python API 文档的生成器。
安装方式:
pip install git+https://github.com/tensorflow/docs
要生成TensorFlow 2.0文档,使用
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/docs的
master
分支构建. 旧版本存储在在GitHub 仓库(repository)下的rX.x
发行版分支中。
简单更改
进行简单文档更新和修复的最简单方法是使用GitHub的 Web文件编辑器。 浏览tensorflow/docs 仓库(repository) 以寻找与 tensorflow.org 中的URL 结构相对应的Markdown或notebook文件。 在文件视图的右上角,单击铅笔图标 来打开文件编辑器。 编辑文件,然后提交新的拉取请求(pull request)。
设置本地Git仓库(repository)
对于多文件编辑或更复杂的更新,最好使用本地Git工作流来创建拉取请求(pull request)。
注意:Git 是用于跟踪源代码更改的开源版本控制系统(VCS)。 GitHub是一种在线服务, 提供与Git配合使用的协作工具。请参阅GitHub Help以设置您的GitHub帐户并开始使用。
只有在第一次设置本地项目时才需要以下Git步骤。
复制(fork) tensorflow/docs 仓库(repository)
在 tensorflow/docs 的Github页码中,点击Fork按钮 在您的GitHub帐户下创建您自己的仓库副本。复制(fork) 完成,您需要保持您的仓库副本副本与上游TensorFlow仓库的同步。
克隆您的仓库(repository)
下载一份您 username/docs 仓库的副本到本地计算机。这是您之后进行操作的工作目录:
git clone git@github.com:username/docs
cd ./docs
添加上游仓库(upstream repo)以保持最新(可选)
要使本地存储库与tensorflow/docs
保持同步,需要添加一个上游(upstream)
仓库来下载最新的更改。
注意:确保在开始撰稿之前更新您的本地仓库。定期向上游同步会降低您在提交拉取请求(pull request)时产生合并冲突(merge conflict)的可能性。
添加远程仓库:
git remote add upstream git@github.com:tensorflow/docs.git
# 浏览远程仓库git remote -v
origin git@github.com:username/docs.git (fetch) origin git@github.com:username/docs.git (push) upstream git@github.com:tensorflow/docs.git (fetch) upstream git@github.com:tensorflow/docs.git (push)
更新:
git checkout master
git pull upstream master
git push
# Push changes to your GitHub account (defaults to origin)
GitHub 工作流
1. 创建一个新分支
从tensorflow / docs
更新您的仓库后,从本地master分支中创建一个新的分支:
git checkout -b feature-name
git branch
# 列出本地分支 master * feature-name
2. 做更改
在您喜欢的编辑器中编辑文件,并请遵守 TensorFlow文档样式指南。
提交文件更改:
# 查看更改git status
# 查看哪些文件被修改git diff
# 查看文件中的更改内容git add path/to/file.md
git commit -m "Your meaningful commit message for the change."
根据需要添加更多提交。
3. 创建一个拉取请求(pull request)
将您的本地分支上传到您的远程GitHub仓库 (github.com/username/docs):
git push
推送完成后,消息可能会显示一个URL,以自动向上游存储库提交拉取请求。如果没有,请转到 tensorflow/docs 仓库—或者您自己的仓库—GitHub将提示您创建拉取请求(pull request)。
4. 审校
维护者和其他贡献者将审核您的拉取请求(pull request)。请参与讨论并根据要求进行修改。当您的请求获得批准后,它将合并到上游TensorFlow文档仓库中。
成功后:您的更改会被TensorFlow文档接受。
从GitHub仓库更新 tensorflow.org是一个单独的步骤。通常情况下,多个更改将被一并处理,并定期上传至网站中。
交互式笔记本(notebook)
虽然可以使用GitHub的web文本编辑器来编辑笔记本JSON文件,但不推荐使用它,因为格式错误的JSON可能会损坏文件。 确保在提交拉取请求(pull request)之前测试笔记本。
Google Colaboratory
是一个托管笔记本环境,可以轻松编辑和运行笔记本文档。 GitHub中的笔记本通过将路径传递给Colab URL(例如,位于GitHub中的笔记本)在Google Colab中加载:
https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras/basic_classification.ipynb
可以通过以下URL链接在Google Colab中加载:
https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/basic_classification.ipynb
有一个
Open in Colab
扩展程序,可以在GitHub上浏览笔记本时执行此URL替换。 这在您复制的仓库中中打开笔记本时非常有用,因为顶部按钮始终链接到TensorFlow Docs的master
分支。
在Colab编辑
在Google Colab环境中,双击单元格以编辑文本和代码块。文本单元格使用Markdown格式,请遵循 TensorFlow文档样式指南.
通过点击 File > Download .pynb 可以从Colab中下载笔记本文件。 将此文件提交到您的本地Git仓库后再提交拉取请求。
如需要创建新笔记本,请复制和编辑 TensorFlow 笔记本模板.
Colab-GitHub工作流
您可以直接从Google Colab编辑和更新复制的GitHub仓库,而不是下载笔记本文件并使用本地Git工作流:
- 在您复制(fork)的 username/docs 仓库中,使用GitHub Web界面 创建新分支。
- 导航到要编辑的笔记本文件。
- 在Google Colab中打开笔记本:使用URL替换或Open in Colab Chrome扩展程序。
- 在Colab中编辑笔记本。
- 通过点击 File > Save a copy in GitHub...从Colab中向GitHub提交更改。保存对话框中选择到相应的仓库与分支。并添加一条有意义的提交消息。
- 保存之后,浏览您的仓库或者 tensorflow/docs 仓库,GitHub会提示您创建一个pull请求。
- 仓库维护者会审核您的拉取请求(pull request)。
成功后:您的更改会被TensorFlow文档接受。
社区翻译
社区翻译是让TensorFlow在全世界都可以访问的好方法。如需更新或添加翻译,在语言目录中按照en/
相同的目录结构找到或添加一个新文件。英语文档是最基础的来源,翻译应尽可能地遵循这些指南。也就是说,翻译应尽量保持原汁原味。如果英语术语,短语,风格或语气不能翻译成其他语言,请采用适合读者的翻译。
注意:请勿翻译 tensorflow.org中的API引用.
有特定于语言的文档组,使翻译贡献者可以更轻松地进行组织。 如果您是作者,评论者或只是想为社区构建TensorFlow.org内容,请加入:
- 简体中文: docs-zh-cn@tensorflow.org
- 日语: docs-ja@tensorflow.org
- 韩语: docs-ko@tensorflow.org
- 俄文: docs-ru@tensorflow.org
- 土耳其语: docs-tr@tensorflow.org
审校须知
所有文档更新都需要审核。 为了更有效地与TensorFlow翻译社区进行协作,以下是一些保持语言特定活动的方法:
- 加入上面列出的语言组,以接收任何涉及该语言
site/lang
目录的已创建的 拉取请求。
在翻译中让代码保持最新
对于像TensorFlow这样的开源项目,保持文档最新是一项挑战。在与社区交谈之后,翻译内容的读者能容忍有点过时的文本,但过时的代码会让人抓狂。为了更容易保持代码同步,请为翻译的笔记本使用 nb-code-sync工具:
./tools/nb_code_sync.py [--lang=en] site/lang/notebook.ipynb
此脚本读取语言笔记本的代码单元格,并根据英语版本进行检查。 剥离注释后,它会比较代码块并更新语言笔记本(如果它们不同)。 此工具对于交互式git工作流特别有用,可以选择性地将文件添加至更改中: git add --patch site/lang/notebook.ipynb
Docs sprint
参加您附近的 TensorFlow 2.0 Global Docs Sprint 活动,或远程加入。 请关注此 博客文章。这些事件是开始为TensorFlow文档做出贡献的好方法。