Question

We welcome contributions to the TensorFlow documentation from the community.
This document explains how you can contribute to that documentation. In
particular, this document explains the following:

• Where the documentation is located.
• How to make conformant edits.
• How to build and test your documentation changes before you submit them.

You can view TensorFlow documentation on https://tensorflow.google.cn , and you
can view and edit the raw files on
GitHub .
We're publishing our docs on GitHub so everybody can contribute. Whatever gets
checked in to tensorflow/docs_src will be published soon after on
https://tensorflow.google.cn .

Republishing TensorFlow documentation in different forms is absolutely allowed,
but we are unlikely to accept other documentation formats (or the tooling to
generate them) into our repository. If you do choose to republish our
documentation in another form, please be sure to include:

• The version of the API this represents (for example, r1.0, master, etc.)
• The commit or version from which the documentation was generated
• Where to get the latest documentation (that is, https://tensorflow.google.cn )
• The Apache 2.0 license.

A note on versions

tensorflow.org, at root, shows documentation for the latest stable binary. This
is the documentation you should be reading if you are using pip to install
TensorFlow.

However, most developers will contribute documentation into the master GitHub
branch, which is published, occasionally,
at tensorflow.org/versions/master .

If you want documentation changes to appear at root, you will need to also
contribute that change to the current stable binary branch (and/or
cherrypick ).

Reference vs. non-reference documentation

The following reference documentation is automatically generated from comments
in the code:

• C++ API reference docs
• Java API reference docs
• Python API reference docs

To modify the reference documentation, you edit the appropriate code comments.

Non-reference documentation (for example, the TensorFlow installation guides) is
authored by humans. This documentation is located in the
tensorflow/docs_src
directory. Each subdirectory of docs_src contains a set of related TensorFlow
documentation. For example, the TensorFlow installation guides are all in the
docs_src/install directory.

The C++ documentation is generated from XML files generated via doxygen;
however, those tools are not available in open source at this time.

Markdown

Editable TensorFlow documentation is written in Markdown. With a few exceptions,
TensorFlow uses
the standard Markdown rules .

This section explains the primary differences between standard Markdown rules
and the Markdown rules that editable TensorFlow documentation uses.

Math in Markdown

You may use MathJax within TensorFlow when editing Markdown files, but note the
following:

• MathJax renders properly on tensorflow.org
• MathJax does not render properly on github .

When writing MathJax, you can use $$ and \\( and \\) to
surround your math. $$ guards will cause line breaks, so
within text, use \\( \\) instead.

Links in Markdown

Links fall into a few categories:

• Links to a different part of the same file
• Links to a URL outside of tensorflow.org
• Links from a Markdown file (or code comments) to another file within tensorflow.org

For the first two link categories, you may use standard Markdown links, but put
the link entirely on one line, rather than splitting it across lines. For
example:

• [text](link) # Good link
• [text]\n(link) # Bad link
• [text](\nlink) # Bad link

For the final link category (links to another file within tensorflow.org),
please use a special link parameterization mechanism. This mechanism enables
authors to move and reorganize files without breaking links.

The parameterization scheme is as follows. Use:

• @{tf.symbol} to make a link to the reference page for a
  Python symbol. Note that class members don't get their own page, but the
  syntax still works, since @{tf.MyClass.method} links to the
  proper part of the tf.MyClass page.
• @{tensorflow::symbol} to make a link to the reference page
  for a C++ symbol.
• @{$doc_page} to make a link to another (not an API reference)
  doc page. To link to
  • red/green/blue/index.md use @{$blue} or
    @{$green/blue} ,
  • foo/bar/baz.md use @{$baz} or
    @{$bar/baz} .

    The shorter one is preferred, so we can move pages around without breaking
    these references. The main exception is that the Python API guides should
    probably be referred to using @{$python/} to
    avoid ambiguity.

• @{$doc_page#anchor-tag$link-text} to link to an anchor in
  that doc and use different link text (by default, the link text is the title
  of the target page).

  To override the link text only, omit the #anchor-tag .

To link to source code, use a link starting with:
https://tensorflow.google.cn/code/ , followed by
the file name starting at the github root. For instance, a link to the file you
are currently reading should be written as
https://tensorflow.google.cn/code/tensorflow/docs_src/community/documentation.md .

This URL naming scheme ensures
that tensorflow.org can forward the link to the
branch of the code corresponding to the version of the documentation you're
viewing. Do not include url parameters in the source code URL.

Generating docs and previewing links

Before building the documentation, you must first set up your environment by
doing the following:

1. If bazel is not installed on your machine, install it now. If you are on
   Linux, install bazel by issuing the following command:

    $ sudo apt-get install bazel  # Linux
   

   If you are on Mac OS, find bazel installation instructions on
   this page .

2. Change directory to the top-level tensorflow directory of the TensorFlow
   source code.
3. Run the configure script and answer its prompts appropriately for your
   system.

    $ ./configure
   

Then, change to the tensorflow directory which contains docs_src ( cd tensorflow ). Run the following command to compile TensorFlow and generate the
documentation in the /tmp/tfdocs dir:

bazel run tools/docs:generate -- \
          --src_dir="$(pwd)/docs_src/" \
          --output_dir=/tmp/tfdocs/

Note: You must set src_dir and output_dir to absolute file paths.

Generating Python API documentation

Ops, classes, and utility functions are defined in Python modules, such as
image_ops.py . Python modules contain a module docstring. For example:

"""Image processing and decoding ops."""

The documentation generator places this module docstring at the beginning of the
Markdown file generated for the module, in this
case, tf.image .

It used to be a requirement to list every member of a module inside the module
file at the beginning, putting a @@ before each member. The @@member_name
syntax is deprecated and no longer generates any docs. But depending on how a
module is sealed it may still be necessary to mark the
elements of the module’s contents as public. The called-out op, function, or
class does not have to be defined in the same file. The next few sections of
this document discuss sealing and how to add elements to the public
documentation.

The new documentation system automatically documents public symbols, except for
the following:

• Private symbols whose names start with an underscore.
• Symbols originally defined in object or protobuf’s Message .
• Some class members, such as __base__ , __class__ , which are dynamically
  created but generally have no useful documentation.

Only top level modules (currently just tf and tfdbg ) need to be manually
added to the generate script.

Sealing modules

Because the doc generator walks all visible symbols, and descends into anything
it finds, it will document any accidentally exposed symbols. If a module only
exposes symbols that are meant to be part of the public API, we call it
sealed . Because of Python’s loose import and visibility conventions, naively
written Python code will inadvertently expose a lot of modules which are
implementation details. Improperly sealed modules may expose other unsealed
modules, which will typically lead the doc generator to fail. This failure is
the intended behavior. It ensures that our API is well defined, and allows us
to change implementation details (including which modules are imported where)
without fear of accidentally breaking users.

If a module is accidentally imported, it typically breaks the doc generator
( generate_test ). This is a clear sign you need to seal your modules. However,
even if the doc generator succeeds, unwanted symbols may show up in the
docs. Check the generated docs to make sure that all symbols that are documented
are expected. If there are symbols that shouldn’t be there, you have the
following options for dealing with them:

• Private symbols and imports
• The remove_undocumented filter
• A traversal blacklist.

We'll discuss these options in detail below.

Private symbols and imports

The easiest way to conform to the API sealing expectations is to make non-public
symbols private (by prepending an underscore _). The doc generator respects
private symbols. This also applies to modules. If the only problem is that there
is a small number of imported modules that show up in the docs (or break the
generator), you can simply rename them on import, e.g.: import sys as _sys .

Because Python considers all files to be modules, this applies to files as
well. If you have a directory containing the following two files/modules:

module/__init__.py
module/private_impl.py

Then, after module is imported, it will be possible to access
module.private_impl . Renaming private_impl.py to _private_impl.py solves
the problem. If renaming modules is awkward, read on.

Use the remove_undocumented filter

Another way to seal a module is to split your implementation from the API. To do
so, consider using remove_undocumented , which takes a list of allowed symbols,
and deletes everything else from the module. For example, the following snippet
demonstrates how to put remove_undocumented in the __init__.py file for a
module:

init .py: