Copyright 2020 The TensorFlow Authors.

#@title Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

Title

[Update button links]

See model on TFHub is only required if the notebook uses a model from tfhub.dev

Overview

[Include a paragraph or two explaining what this example demonstrates, who should be interested in it, and what you need to know before you get started.]

Setup

[Put all your imports and installs up into a setup section.]

import tensorflow as tf

import numpy as np

Resources

• TensorFlow documentation contributor guide
• TensorFlow documentation style guide
• Google developer documentation style guide

Notebook style

• Include the collapsed license at the top (uses the Colab "Form" mode to hide the cells).
• Save the notebook with the table of contents open.
• Use one H1 header for the title.
• Include the button-bar immediately after the H1.
• Headers that areH4 and below are not visible in the navigation bar of tensorflow.org.
• Include an overview section before any code.
• Put all your installs and imports in a setup section.
• Keep code and text cells as brief as possible.
• Break text cells at headings
• Break code cells between "building" and "running", and between "printing one result" and "printing another result".
• Necessary but uninteresting code (like plotting logic) should be hidden in a toggleable code cell by putting #@title as the first line.

Code style

• Notebooks are for people. Write code optimized for clarity.
• Use the Google Python Style Guide, where applicable.
• tensorflow.org doesn't support interactive plots.
• Keep examples quick. Use small datasets, or small slices of datasets. Don't train to convergence, train until it's obvious it's making progress.
• If you define a function, run it and show us what it does before using it in another function.
• Demonstrate small parts before combining them into something more complex, like this:

# Build the model
model = tf.keras.Sequential([
    tf.keras.layers.Dense(10, activation='relu', input_shape=(None, 5)),
    tf.keras.layers.Dense(3)
])

Run the model on a single batch of data, and inspect the output:

result = model(tf.constant(np.random.randn(10,5), dtype = tf.float32)).numpy()

print("min:", result.min())
print("max:", result.max())
print("mean:", result.mean())
print("shape:", result.shape)

Compile the model for training:

model.compile(optimizer=tf.keras.optimizers.Adam(),
              loss=tf.keras.losses.categorical_crossentropy)

Code content

• Use the highest level API that gets the job done (unless the goal is to demonstrate the low level API).
• Use keras.Sequential > keras functional api > keras model subclassing > ...
• Use model.fit > model.train_step > manual GradientTapes.
• Use tensorflow_datasets and tf.data where possible.
• When using pre-trained models, prefer models from tfhub.dev where possible.
• Avoid compat.v1.

Text

• Use an imperative style. "Run a batch of images through the model."
• Use sentence case in titles/headings.
• Use short titles/headings: "Download the data", "Build the model", "Train the model".
• Use the Google developer documentation style guide.

GitHub workflow

• Be consistent about how you save your notebooks, otherwise the JSON diffs are messy.
• This notebook has the "Omit code cell output when saving this notebook" option set. GitHub refuses to diff notebooks with large diffs (inline images).
• ReviewNB.com can help with diffs. This is linked in a comment on a notebook pull request.
• Use the Open in Colab extension to open a GitHub notebook in Colab.
• The easiest way to edit a notebook in GitHub is to open it with Colab from the branch you want to edit. Then use File --> Save a copy in GitHub, which will save it back to the branch you opened it from.
• For PRs it's helpful to post a direct Colab link to the PR head: https://colab.research.google.com/github/{USER}/{REPO}/blob/{BRANCH}/{PATH}.ipynb