TensorFlow welcomes documentation contributions—if you improve the documentation, you improve the TensorFlow library itself. Documentation on tensorflow.org falls into the following categories:
- API reference —The API reference docs are generated from docstrings in the TensorFlow source code.
- Narrative documentation —These are tutorials, guides, and other writing that's not part of the TensorFlow code. This documentation is in the tensorflow/docs GitHub repository.
- Community translations —These are guides and tutorials translated by the community. All community translations live in the tensorflow/docs repo.
Some TensorFlow projects keep documentation
source files near the code in a separate repository, usually in a
directory. See the project's
CONTRIBUTING.md file or contact the maintainer to
To participate in the TensorFlow docs community:
To update reference documentation, find the source file and edit the symbol's docstring. Many API reference pages on tensorflow.org include a link to the source file where the symbol is defined. Docstrings support Markdown and can be (approximately) previewed using any Markdown previewer.
For reference documentation quality and how to get involved with doc sprints and the community, see the TensorFlow 2 API Docs advice.
Versions and branches
The site's API reference
version defaults to the latest stable binary—this matches the package installed
pip install tensorflow.
The default TensorFlow package is built from the stable branch
rX.x in the
repo. The reference documentation is generated from code comments
and docstrings in the source code for
Previous versions of the TensorFlow documentation are available as rX.x branches in the TensorFlow Docs repository. These branches are added when a new version is released.
Build API docs
tensorflow_docs package includes the generator for the
Python API reference docs. To
pip install git+https://github.com/tensorflow/docs
To generate the TensorFlow 2 reference docs, use the
git clone https://github.com/tensorflow/tensorflow tensorflow
pip install tensorflow
python generate2.py --output_dir=/tmp/out
TensorFlow guides and
tutorials are written as
files and interactive
Jupyter notebooks. Notebooks
can be run in your browser using
The narrative docs on tensorflow.org are built
master branch. Older versions are available in GitHub on the
The easiest way to make straightforward documentation updates to Markdown files is to use GitHub's web-based file editor. Browse the tensorflow/docs repository to find the Markdown that roughly corresponds to the tensorflow.org URL structure. In the upper right corner of the file view, click the pencil icon to open the file editor. Edit the file and then submit a new pull request.
Set up a local Git repo
For multi-file edits or more complex updates, it's better to use a local Git workflow to create a pull request.
The following Git steps are only required the first time you set up a local project.
Fork the tensorflow/docs repo
On the tensorflow/docs GitHub page, click the Fork button to create your own repo copy under your GitHub account. Once forked, you're responsible for keeping your repo copy up-to-date with the upstream TensorFlow repo.
Clone your repo
Download a copy of your remote username/docs repo to your local machine. This is the working directory where you will make changes:
git clone firstname.lastname@example.org:username/docs
Add an upstream repo to keep up-to-date (optional)
To keep your local repository in sync with
tensorflow/docs, add an upstream
remote to download the latest changes.
Add a remote:
git remote add upstream email@example.com:tensorflow/docs.git# View remote repos
git remote -vorigin firstname.lastname@example.org:username/docs.git (fetch) origin email@example.com:username/docs.git (push) upstream firstname.lastname@example.org:tensorflow/docs.git (fetch) upstream email@example.com:tensorflow/docs.git (push)
git checkout master
git pull upstream master
git push# Push changes to your GitHub account (defaults to origin)
1. Create a new branch
After you update your repo from
tensorflow/docs, create a new branch from the
local master branch:
git checkout -b feature-name
git branch# List local branches master * feature-name
2. Make changes
Edit files in your favorite editor and please follow the TensorFlow documentation style guide.
Commit your file change:
# View changes
git status# See which files have changed
git diff# See changes within files
git add path/to/file.md
git commit -m "Your meaningful commit message for the change."
Add more commits, as necessary.
3. Create a pull request
Upload your local branch to your remote GitHub repo (github.com/username/docs):
After the push completes, a message may display a URL to automatically submit a pull request to the upstream repo. If not, go to the tensorflow/docs repo—or your own repo—and GitHub will prompt you to create a pull request.
Maintainers and other contributors will review your pull request. Please participate in the discussion and make the requested changes. When your pull request is approved, it will be merged into the upstream TensorFlow docs repo.
There is a separate publishing step to update tensorflow.org from the GitHub repo. Typically, changes are batched together and the site is updated on a regular cadence.
While it's possible to edit the notebook JSON file with GitHub's web-based file editor, it's not recommended since malformed JSON can corrupt the file. Make sure to test the notebook before submitting a pull request.
is a hosted notebook environment that makes it easy to edit—and run—notebook
documentation. Notebooks in GitHub are loaded in Google Colab by passing the
path to the Colab URL, for example,
the notebook located in GitHub here:
can be loaded into Google Colab at this URL: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb
There is an
Open in Colab
Chrome extension that performs this URL substitution when browsing a notebook on
GitHub. This is useful when opening a notebook in your repo fork, because the
top buttons always link to the TensorFlow Docs
To create a new notebook, copy and edit the TensorFlow notebook template.
Notebooks are stored on disk as JSON and the various notebook implementations format the JSON differently. Diff tools and version control don't handle this very well, so TensorFlow Docs enforces a standard notebook formatting.
nbfmt command to apply this formattng:
# Install the tensorflow-docs package: $ python3 -m pip install -U [--user] git+https://github.com/tensorflow/docs # Format individual notebooks: $ python3 -m tensorflow_docs.tools.nbfmt ./path/to/notebook.ipynb [...] # Or a directory of notebooks: $ python3 -m tensorflow_docs.tools.nbfmt ./path/to/notebooks/
For the same reasons notebook output should be cleared before submission
(except in a few special cases). In Colab the "private outputs" option is used
to enforce this. Other notebook implementations do not recognize this option.
You can clear the outputs by passing
$ python3 -m tensorflow_docs.tools.nbfmt --preserve_outputs=False \ path/to/notebooks/example.ipynb
Edit in Colab
Within the Google Colab environment, double-click cells to edit text and code blocks. Text cells use Markdown and should follow the TensorFlow docs style guide.
Download notebook files from Colab with File > Download .pynb. Commit this file to your local Git repo and send a pull request.
To create a new notebook, copy and edit the TensorFlow notebook template.
Instead of downloading a notebook file and using a local Git workflow, you can edit and update your forked GitHub repo directly from Google Colab:
- In your forked username/docs repo, use the GitHub web UI to create a new branch.
- Navigate to the notebook file to edit.
- Open the notebook in Google Colab: use the URL swap or the Open in Colab Chrome extension.
- Edit the notebook in Colab.
- Commit the changes to your repo from Colab with File > Save a copy in GitHub.... The save dialog should link to the appropriate repo and branch. Add a meaningful commit message.
- After saving, browse to your repo or the tensorflow/docs repo, GitHub should prompt you to create a pull request.
- The pull request is reviewed by maintainers.
Community translations are a great way to make TensorFlow accessible all over
the world. To update a translation, find or add a file in the
language directory that
matches the same directory structure of the
en/ directory. The English docs
are the source-of-truth and translations should follow these guides as close
as possible. That said, translations are written for the communities they serve.
If the English terminology, phrasing, style, or tone does not translate to
another language, please use a translation appropriate for the reader.
There are language-specific docs groups that make it easier for translation contributors to organize. Please join if you're an author, reviewer, or just interested in building out TensorFlow.org content for the community:
- Chinese (Simplified): firstname.lastname@example.org
- Italian: email@example.com
- Japanese: firstname.lastname@example.org
- Korean: email@example.com
- Russian: firstname.lastname@example.org
- Turkish: email@example.com
All documentation updates require a review. To collaborate more efficiently with the TensorFlow translation communities, here are some ways to keep on top of language-specific activity:
- Join a language group listed above to receive an email for any created pull
request that touches the
site/langdirectory for that language.
- Add your GitHub username to the
site/<lang>/REVIEWERSfile to get automatically comment-tagged in a pull request. When comment-tagged, GitHub will send you notifications for all changes and discussion in that pull request.
Keep code up-to-date in translations
For an open source project like TensorFlow, keeping documentation up-to-date is challenging. After talking with the community, readers of translated content will tolerate text that is a little out-of-date, but out-of-date code is frustrating. To make it easier to keep the code in sync, use the nb-code-sync tool for the translated notebooks:
./tools/nb_code_sync.py [--lang=en] site/lang/notebook.ipynb
This script reads the code cells of a language notebook and checks it against the
English version. After stripping the comments, it compares the code blocks and
updates the language notebook if they are different. This tool is particularly
useful with an interactive git workflow to selectively add hunks of the file to
the commit using:
git add --patch site/lang/notebook.ipynb