# Contribute to the TensorFlow documentation

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](https://www.tensorflow.org/api_docs/) are generated from docstrings in the [TensorFlow source code](https://github.com/tensorflow/tensorflow).
- *Narrative documentation* ---These are [tutorials](https://www.tensorflow.org/tutorials), [guides](https://www.tensorflow.org/guide), and other writing that's not part of the TensorFlow code. This documentation is in the [tensorflow/docs](https://github.com/tensorflow/docs) GitHub repository.
- *Community translations* ---These are guides and tutorials translated by the community. All community translations live in the [tensorflow/docs](https://github.com/tensorflow/docs/tree/master/site) repo.

Some [TensorFlow projects](https://github.com/tensorflow) keep documentation
source files near the code in a separate repository, usually in a `docs/`
directory. See the project's `CONTRIBUTING.md` file or contact the maintainer to
contribute.

To participate in the TensorFlow docs community:

- Watch the [tensorflow/docs](https://github.com/tensorflow/docs) GitHub repository.
- Follow the [docs](https://discuss.tensorflow.org/tag/docs) tag on the [TensorFlow Forum](https://discuss.tensorflow.org/).

## API reference

For details, use the [TensorFlow API docs contributor guide](https://www.tensorflow.org/community/contribute/docs_ref). This
shows you how to find the
[source file](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/)
and edit the symbol's
[docstring](https://www.python.org/dev/peps/pep-0257/).
Many API reference pages on tensorflow.org include a link to the source file
where the symbol is defined. Docstrings support
[Markdown](https://help.github.com/en/articles/about-writing-and-formatting-on-github)
and can be (approximately) previewed using any
[Markdown previewer](http://tmpvar.com/markdown.html).

### Versions and branches

The site's [API reference](https://www.tensorflow.org/api_docs/python/tf)
version defaults to the latest stable binary---this matches the package installed
with `pip install tensorflow`.

The default TensorFlow package is built from the stable branch `rX.x` in the
main
[tensorflow/tensorflow](https://github.com/tensorflow/tensorflow)
repo. The reference documentation is generated from code comments
and docstrings in the source code for
[Python](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/),
[C++](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/cc/), and
[Java](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/java/).

Previous versions of the TensorFlow documentation are available as
[rX.x branches](https://github.com/tensorflow/docs/branches) in the TensorFlow
Docs repository. These branches are added when a new version is released.

### Build API docs

> [!NOTE]
> **Note:** This step is not required to edit or preview API docstrings, only to generate the HTML used on tensorflow.org.

#### Python reference

The `tensorflow_docs` package includes the generator for the
[Python API reference docs](https://www.tensorflow.org/api_docs/python/tf). To
install:

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

To generate the TensorFlow 2 reference docs, use the
`tensorflow/tools/docs/generate2.py` script:

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

> [!NOTE]
> **Note:** This script uses the *installed* TensorFlow package to generate docs and only works for TensorFlow 2.x.

## Narrative documentation

TensorFlow [guides](https://www.tensorflow.org/guide) and
[tutorials](https://www.tensorflow.org/tutorials) are written as
[Markdown](https://guides.github.com/features/mastering-markdown/)
files and interactive
[Jupyter](https://jupyter.org/) notebooks. Notebooks
can be run in your browser using
[Google Colaboratory](https://colab.research.google.com/notebooks/welcome.ipynb).
The narrative docs on [tensorflow.org](https://www.tensorflow.org) are built
from the
[tensorflow/docs](https://github.com/tensorflow/docs)
`master` branch. Older versions are available in GitHub on the `rX.x` release
branches.

### Simple changes

The easiest way to make straightforward documentation updates to Markdown files
is to use GitHub's
[web-based
file editor](https://help.github.com/en/articles/editing-files-in-your-repository). Browse the
[tensorflow/docs](https://github.com/tensorflow/docs/tree/master/site/en)
repository to find the Markdown that roughly corresponds to the
[tensorflow.org](https://www.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.

> [!NOTE]
> **Note:** [Git](https://git-scm.com/) is the open source version control system (VCS) used to track changes to source code. [GitHub](https://github.com) is an online service that provides collaboration tools that work with Git. See the [GitHub Help](https://help.github.com) to set up your GitHub account and get started.

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](https://github.com/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 <var translate="no">username</var>/docs repo to your local
machine. This is the working directory where you will make changes:

    git clone git@github.com:username/docs
    cd ./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.

> [!NOTE]
> **Note:** Make sure to update your local repo *before* starting a contribution. Regular syncs to upstream reduce the chance of a [merge conflict](https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line) when you submit your pull request.

Add a remote:

    git remote add upstream git@github.com:tensorflow/docs.git

    # View remote repos
    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)

To update:

    git checkout master
    git pull upstream master

    git push  # Push changes to your GitHub account (defaults to origin)

### GitHub workflow

#### 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](https://www.tensorflow.org/community/contribute/docs_style).

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/<var translate="no">username</var>/docs):

    git push

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](https://github.com/tensorflow/docs)
repo---or your own repo---and GitHub will prompt you to create a pull request.

#### 4. Review

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.

> [!TIP]
> **Success:** Your changes have been accepted to the TensorFlow documentation.

There is a separate publishing step to update
[tensorflow.org](https://www.tensorflow.org) from the GitHub repo. Typically,
changes are batched together and the site is updated on a regular cadence.

## Interactive notebooks

While it's possible to edit the notebook JSON file with GitHub's
[web-based file editor](https://help.github.com/en/articles/editing-files-in-your-repository),
it's not recommended since malformed JSON can corrupt the file. Make sure to
test the notebook before submitting a pull request.

[Google Colaboratory](https://colab.research.google.com/notebooks/welcome.ipynb)
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:
<https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb>  

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](https://chrome.google.com/webstore/detail/open-in-colab/iogfkhleblhcpcekbiedikdehleodpjo)
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 `master` branch.

### Notebook formatting

A notebook formatting tool makes Jupyter notebook source diffs consistent and
easier to review. Since notebook authoring environments differ with regards to
file output, indentation, metadata and other non-specified fields; `nbfmt` uses
opinionated defaults with a preference for the TensorFlow docs Colab workflow.
To format a notebook, install the
[TensorFlow
docs notebook tools](https://github.com/tensorflow/docs/tree/master/tools/tensorflow_docs/tools/) and run the `nbfmt` tool:

    # 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 [...]

For TensorFlow docs projects, notebooks *without* output cells are executed and
tested; notebooks *with* saved output cells are published as-is. `nbfmt`
respects the notebook state and uses the `--remove_outputs` option to explicitly
remove output cells.

To create a new notebook, copy and edit the
[TensorFlow
docs notebook template](https://github.com/tensorflow/docs/blob/master/tools/templates/notebook.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](https://www.tensorflow.org/community/contribute/docs_style).

Download notebook files from Colab with *File \> Download .pynb* . Commit
this file to your [local Git repo](https://www.tensorflow.org/community/contribute/docs##set_up_a_local_git_repo) and send a pull
request.

To create a new notebook, copy and edit the
[TensorFlow notebook template](https://github.com/tensorflow/docs/blob/master/tools/templates/notebook.ipynb).

### Colab-GitHub workflow

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:

1. In your forked <var translate="no">username</var>/docs repo, use the GitHub web UI to [create a new branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository).
2. Navigate to the notebook file to edit.
3. Open the notebook in Google Colab: use the URL swap or the *Open in Colab* Chrome extension.
4. Edit the notebook in Colab.
5. 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.
6. After saving, browse to your repo or the [tensorflow/docs](https://github.com/tensorflow/docs) repo, GitHub should prompt you to create a pull request.
7. The pull request is reviewed by maintainers.

> [!TIP]
> **Success:** Your changes have been accepted to the TensorFlow documentation.

## Translations

The TensorFlow team works with the community and vendors to provide translations
for tensorflow.org. Translations of notebooks and other technical content are
located in the
[tensorflow/docs-l10n](https://github.com/tensorflow/docs-l10n)
GitHub repo. Please submit pull requests through the
[TensorFlow
GitLocalize project](https://gitlocalize.com/tensorflow/docs-l10n).

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.

Language support is determined by a number of factors including---but not limited
to---site metrics and demand, community support,
[English
proficiency](https://en.wikipedia.org/wiki/EF_English_Proficiency_Index), audience preference, and other indicators. Since each supported
language incurs a cost, unmaintained languages are removed. Support for new
languages will be announced on the
[TensorFlow blog](https://blog.tensorflow.org/) or
[Twitter](https://twitter.com/TensorFlow).

If your preferred language is not supported, you are welcome to maintain a
community fork for open source contributors. These are not published to
tensorflow.org.