Question

from tensorflow.some_module.some_file import *

# Otherwise import symbols directly
from tensorflow.some_module.some_other_file import some_symbol

from tensorflow.python.util.all_util import remove_undocumented

_allowed_symbols = [‘some_symbol’, ‘some_other_symbol’]

remove_undocumented(__name__, allowed_exception_list=_allowed_symbols)

The @@member_name syntax is deprecated, but it still exists in some places in
the documentation as an indicator to remove_undocumented that those symbols
are public. All @@ s will eventually be removed. If you see them, however,
please do not randomly delete them as they are still in use by some of our
systems.

Traversal blacklist

If all else fails, you may add entries to the traversal blacklist in
generate_lib.py. Almost all entries in this list are an abuse of its
purpose; avoid adding to it if you can!

The traversal blacklist maps qualified module names (without the leading tf. )
to local names that are not to be descended into. For instance, the following
entry will exclude some_module from traversal.

{ ...
  ‘contrib.my_module’: [‘some_module’]
  ...
}

That means that the doc generator will show that some_module exists, but it
will not enumerate its content.

This blacklist was originally intended to make sure that system modules (mock,
flags, ...) included for platform abstraction can be documented without
documenting their interior. Its use beyond this purpose is a shortcut that may
be acceptable for contrib, but not for core tensorflow.

Op documentation style guide

Long, descriptive module-level documentation for modules should go in the API
Guides in docs_src/api_guides/python .

For classes and ops, ideally, you should provide the following information, in
order of presentation:

• A short sentence that describes what the op does.
• A short description of what happens when you pass arguments to the op.
• An example showing how the op works (pseudocode is best).
• Requirements, caveats, important notes (if there are any).
• Descriptions of inputs, outputs, and Attrs or other parameters of the op
  constructor.

Each of these is described in more
detail below .

Write your text in Markdown format. A basic syntax reference
is here . You are allowed to
use MathJax notation for equations (see above for
restrictions).

Writing about code

Put backticks around these things when they're used in text:

• Argument names (for example, input , x , tensor )
• Returned tensor names (for example, output , idx , out )
• Data types (for example, int32 , float , uint8 )
• Other op names referenced in text (for example, list_diff() , shuffle() )
• Class names (for example, Tensor when you actually mean a Tensor object;
  don't capitalize or use backticks if you're just explaining what an op does to
  a tensor, or a graph, or an operation in general)
• File names (for example, image_ops.py , or
  /path-to-your-data/xml/example-name )
• Math expressions or conditions (for example, -1-input.dims() <= dim <= input.dims() )

Put three backticks around sample code and pseudocode examples. And use ==>
instead of a single equal sign when you want to show what an op returns. For
example:

    # 'input' is a tensor of shape [2, 3, 5]
    (tf.expand_dims(input, 0)) ==> [1, 2, 3, 5]

If you're providing a Python code sample, add the python style label to ensure
proper syntax highlighting:

    # some Python code

Two notes about backticks for code samples in Markdown:

1. You can use backticks for pretty printing languages other than Python, if
   necessary. A full list of languages is available
   here .
2. Markdown also allows you to indent four spaces to specify a code sample.
   However, do NOT indent four spaces and use backticks simultaneously. Use one
   or the other.

Tensor dimensions

When you're talking about a tensor in general, don't capitalize the word tensor.
When you're talking about the specific object that's provided to an op as an
argument or returned by an op, then you should capitalize the word Tensor and
add backticks around it because you're talking about a Tensor object.

Don't use the word Tensors to describe multiple Tensor objects unless you
really are talking about a Tensors object. Better to say "a list of Tensor
objects."

Use the term "dimension" to refer to the size of a tensor. If you need to be
specific about the size, use these conventions:

• Refer to a scalar as a "0-D tensor"
• Refer to a vector as a "1-D tensor"
• Refer to a matrix as a "2-D tensor"
• Refer to tensors with 3 or more dimensions as 3-D tensors or n-D tensors. Use
  the word "rank" only if it makes sense, but try to use "dimension" instead.
  Never use the word "order" to describe the size of a tensor.

Use the word "shape" to detail the dimensions of a tensor, and show the shape in
square brackets with backticks. For example:

If `input` is a 3-D tensor with shape `[3, 4, 3]`, this operation
returns a 3-D tensor with shape `[6, 8, 6]`.

Ops defined in C++

All Ops defined in C++ (and accessible from other languages) must be documented
with a REGISTER_OP declaration. The docstring in the C++ file is processed to
automatically add some information for the input types, output types, and Attr
types and default values.

For example:

    REGISTER_OP("PngDecode")
      .Input("contents: string")
      .Attr("channels: int = 0")
      .Output("image: uint8")
      .Doc(R"doc(
    Decodes the contents of a PNG file into a uint8 tensor.

    contents: PNG file contents.
    channels: Number of color channels, or 0 to autodetect based on the input.
      Must be 0 for autodetect, 1 for grayscale, 3 for RGB, or 4 for RGBA.
      If the input has a different number of channels, it will be transformed
      accordingly.
    image:= A 3-D uint8 tensor of shape `[height, width, channels]`.
      If `channels` is 0, the last dimension is determined
      from the png contents.
    )doc");

Results in this piece of Markdown:

tf.image.png_decode(contents, channels=None, name=None) {#png_decode}

Decodes the contents of a PNG file into a uint8 tensor.

#### Args:

*  <b>contents</b>: A string Tensor. PNG file contents.
*  <b>channels</b>: An optional int. Defaults to 0.
   Number of color channels, or 0 to autodetect based on the input.
   Must be 0 for autodetect, 1 for grayscale, 3 for RGB, or 4 for RGBA.  If the
   input has a different number of channels, it will be transformed accordingly.
*  <b>name</b>: A name for the operation (optional).

#### Returns:
A 3-D uint8 tensor of shape `[height, width, channels]`.  If `channels` is
0, the last dimension is determined from the png contents.

Much of the argument description is added automatically. In particular, the doc
generator automatically adds the name and type of all inputs, attrs, and
outputs. In the above example, <b>contents</b>: A string Tensor. was added
automatically. You should write your additional text to flow naturally after
that description.

For inputs and output, you can prefix your additional text with an equal sign to
prevent the automatically added name and type. In the above example, the
description for the output named image starts with = to prevent the addition
of A uint8 Tensor. before our text A 3-D uint8 Tensor... . You cannot prevent
the addition of the name, type, and default value of attrs this way, so write
your text carefully.

Ops defined in Python

If your op is defined in a python/ops/*.py file, then you need to provide text
for all of the arguments and output (returned) tensors. The doc generator does
not auto-generate any text for ops that are defined in Python, so what you write
is what you get.

You should conform to the usual Python docstring conventions, except that you
should use Markdown in the docstring.

Here's a simple example:

def foo(x, y, name="bar"):
  """Computes foo.

  Given two 1-D tensors `x` and `y`, this operation computes the foo.

  Example:

  ```
  # x is [1, 1]
  # y is [2, 2]
  tf.foo(x, y) ==> [3, 3]
  ```
  Args:
    x: A `Tensor` of type `int32`.
    y: A `Tensor` of type `int32`.
    name: A name for the operation (optional).

  Returns:
    A `Tensor` of type `int32` that is the foo of `x` and `y`.

  Raises:
    ValueError: If `x` or `y` are not of type `int32`.
  """

Description of the docstring sections

This section details each of the elements in docstrings.

Short sentence describing what the op does

Examples:

Concatenates tensors.

Flips an image horizontally from left to right.

Computes the Levenshtein distance between two sequences.

Saves a list of tensors to a file.

Extracts a slice from a tensor.

Short description of what happens when you pass arguments to the op

Examples:

Given a tensor input of numerical type, this operation returns a tensor of
the same type and size with values reversed along dimension `seq_dim`. A
vector `seq_lengths` determines which elements are reversed for each index
within dimension 0 (usually the batch dimension).


This operation returns a tensor of type `dtype` and dimensions `shape`, with
all elements set to zero.

Example demonstrating the op

Good code samples are short and easy to understand, typically containing a brief
snippet of code to clarify what the example is demonstrating. When an op
manipulates the shape of a Tensor it is often useful to include an example of
the before and after, as well.

The squeeze() op has a nice pseudocode example: