• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Copyright 2018 The TensorFlow Authors. All Rights Reserved.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#     http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14# ==============================================================================
15r"""A tool to generate api_docs for TensorFlow2.
16
17```
18python generate2.py --output_dir=/tmp/out
19```
20
21Requires a local installation of:
22  https://github.com/tensorflow/docs/tree/master/tools
23  tf-nightly-2.0-preview
24"""
25
26from __future__ import absolute_import
27from __future__ import division
28from __future__ import print_function
29
30from os import path
31
32from absl import app
33from absl import flags
34import tensorflow as tf
35
36from tensorflow_docs.api_generator import doc_controls
37from tensorflow_docs.api_generator import doc_generator_visitor
38from tensorflow_docs.api_generator import generate_lib
39from tensorflow_docs.api_generator import parser
40
41import tensorboard
42import tensorflow_estimator
43from tensorflow.python.util import tf_export
44from tensorflow.python.util import tf_inspect
45
46# Use tensorflow's `tf_inspect`, which is aware of `tf_decorator`.
47parser.tf_inspect = tf_inspect
48
49# `tf` has an `__all__` that doesn't list important things like `keras`.
50# The doc generator recognizes `__all__` as the list of public symbols.
51# So patch `tf.__all__` to list everything.
52tf.__all__ = [item_name for item_name, value in tf_inspect.getmembers(tf)]
53
54
55FLAGS = flags.FLAGS
56
57flags.DEFINE_string(
58    "code_url_prefix",
59    "/code/stable/tensorflow",
60    "A url to prepend to code paths when creating links to defining code")
61
62flags.DEFINE_string(
63    "output_dir", "/tmp/out",
64    "A directory, where the docs will be output to.")
65
66flags.DEFINE_bool("search_hints", True,
67                  "Include meta-data search hints at the top of each file.")
68
69flags.DEFINE_string("site_path", "",
70                    "The prefix ({site-path}/api_docs/python/...) used in the "
71                    "`_toc.yaml` and `_redirects.yaml` files")
72
73
74# The doc generator isn't aware of tf_export.
75# So prefix the score tuples with -1 when this is the canonical name, +1
76# otherwise. The generator chooses the name with the lowest score.
77class TfExportAwareDocGeneratorVisitor(
78    doc_generator_visitor.DocGeneratorVisitor):
79  """A `tf_export` aware doc_visitor."""
80
81  def _score_name(self, name):
82    canonical = tf_export.get_canonical_name_for_symbol(self._index[name])
83
84    canonical_score = 1
85    if canonical is not None and name == "tf." + canonical:
86      canonical_score = -1
87
88    scores = super(TfExportAwareDocGeneratorVisitor, self)._score_name(name)
89    return (canonical_score,) + scores
90
91
92def build_docs(output_dir, code_url_prefix, search_hints=True):
93  """Build api docs for tensorflow v2.
94
95  Args:
96    output_dir: A string path, where to put the files.
97    code_url_prefix: prefix for "Defined in" links.
98    search_hints: Bool. Include meta-data search hints at the top of each file.
99  """
100  try:
101    doc_controls.do_not_generate_docs(tf.tools)
102  except AttributeError:
103    pass
104
105  base_dir = path.dirname(tf.__file__)
106  base_dirs = (
107      base_dir,
108      path.normpath(path.join(base_dir, "../../tensorflow")),
109      path.dirname(tensorboard.__file__),
110      path.dirname(tensorflow_estimator.__file__),
111  )
112
113  code_url_prefixes = (
114      code_url_prefix,
115      # External packages source repositories
116      "https://github.com/tensorflow/tensorboard/tree/master/tensorboard"
117      "https://github.com/tensorflow/estimator/tree/master/tensorflow_estimator"
118  )
119
120  doc_generator = generate_lib.DocGenerator(
121      root_title="TensorFlow 2.0 Preview",
122      py_modules=[("tf", tf)],
123      base_dir=base_dirs,
124      search_hints=search_hints,
125      code_url_prefix=code_url_prefixes,
126      site_path=FLAGS.site_path,
127      visitor_cls=TfExportAwareDocGeneratorVisitor)
128
129  doc_generator.build(output_dir)
130
131
132def main(argv):
133  del argv
134  build_docs(output_dir=FLAGS.output_dir,
135             code_url_prefix=FLAGS.code_url_prefix,
136             search_hints=FLAGS.search_hints)
137
138
139if __name__ == "__main__":
140  app.run(main)
141