1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
# Copyright 2015 Google Inc. All Rights Reserved.
#
# 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
#
# http://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.
# ==============================================================================
"""Updates generated docs from Python doc comments."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import os.path
import tensorflow.python.platform
import sys
import tensorflow as tf
from tensorflow.python.framework import docs
from tensorflow.python.framework import framework_lib
from tensorflow.python.client import client_lib
tf.flags.DEFINE_string("out_dir", None,
"Directory to which docs should be written.")
tf.flags.DEFINE_boolean("print_hidden_regex", False,
"Dump a regular expression matching any hidden symbol")
FLAGS = tf.flags.FLAGS
# TODO(josh11b,wicke): Remove the ../../api_docs/python/ once the
# website can handle it.
PREFIX_TEXT = """
Note: Functions taking `Tensor` arguments can also take anything accepted by
[`tf.convert_to_tensor`](../../api_docs/python/framework.md#convert_to_tensor).
"""
def get_module_to_name():
return {tf: 'tf',
tf.errors: 'tf.errors',
tf.image: 'tf.image',
tf.nn: 'tf.nn',
tf.train: 'tf.train',
tf.python_io: 'tf.python_io'}
def all_libraries(module_to_name, members, documented):
# A list of (filename, docs.Library) pairs representing the individual files
# that we want to create.
def library(name, title, module=None, **args):
if module is None:
module = sys.modules["tensorflow.python.ops" +
("" if name == "ops" else "." + name)]
return (name + ".md", docs.Library(title=title,
module_to_name=module_to_name,
members=members,
documented=documented,
module=module,
**args))
return [
# Splits of module 'tf'.
library("framework", "Building Graphs", framework_lib),
library("constant_op", "Constants, Sequences, and Random Values",
prefix=PREFIX_TEXT),
library("state_ops", "Variables", prefix=PREFIX_TEXT),
library("array_ops", "Tensor Transformations",
exclude_symbols=["list_diff"], prefix=PREFIX_TEXT),
library("math_ops", "Math",
exclude_symbols=["sparse_matmul", "arg_min", "arg_max",
"lin_space", "sparse_segment_mean_grad"],
prefix=PREFIX_TEXT),
library("control_flow_ops", "Control Flow", prefix=PREFIX_TEXT),
library("image", "Images", tf.image, exclude_symbols=["ResizeMethod"],
prefix=PREFIX_TEXT),
library("sparse_ops", "Sparse Tensors", prefix=PREFIX_TEXT),
library("io_ops", "Inputs and Readers",
exclude_symbols=["LookupTableBase", "HashTable",
"initialize_all_tables",
"string_to_hash_bucket"],
prefix=PREFIX_TEXT),
library("python_io", "Data IO (Python functions)", tf.python_io),
library("nn", "Neural Network", tf.nn,
exclude_symbols=["deconv2d", "conv2d_backprop_input",
"conv2d_backprop_filter", "avg_pool_grad",
"max_pool_grad", "max_pool_grad_with_argmax",
"batch_norm_with_global_normalization_grad",
"lrn_grad", "relu6_grad", "softplus_grad",
"xw_plus_b", "relu_layer", "lrn",
"batch_norm_with_global_normalization",
"batch_norm_with_global_normalization_grad",
"all_candidate_sampler",
"embedding_lookup_sparse"],
prefix=PREFIX_TEXT),
library('client', "Running Graphs", client_lib),
library("train", "Training", tf.train,
exclude_symbols=["Feature", "Features", "BytesList", "FloatList",
"Int64List", "Example", "InferenceExample",
"RankingExample", "SequenceExample"]),
]
_hidden_symbols = ["Event", "Summary", "xrange",
"HistogramProto", "ConfigProto", "NodeDef", "GraphDef",
"GPUOptions", "SessionInterface", "BaseSession"]
def main(unused_argv):
if not FLAGS.out_dir:
tf.logging.error("out_dir not specified")
return -1
# Document libraries
documented = set()
module_to_name = get_module_to_name()
members = docs.collect_members(module_to_name)
libraries = all_libraries(module_to_name, members, documented)
# Define catch_all library before calling write_libraries to avoid complaining
# about generically hidden symbols.
catch_all = docs.Library(title="Catch All", module=None,
exclude_symbols=_hidden_symbols,
module_to_name=module_to_name, members=members,
documented=documented)
# Write docs to files
docs.write_libraries(FLAGS.out_dir, libraries)
# Make it easy to search for hidden symbols
if FLAGS.print_hidden_regex:
hidden = set(_hidden_symbols)
for _, lib in libraries:
hidden.update(lib.exclude_symbols)
print(r"hidden symbols regex = r'\b(%s)\b'" % "|".join(sorted(hidden)))
# Verify that all symbols are mentioned in some library doc.
catch_all.assert_no_leftovers()
# Generate index
with open(os.path.join(FLAGS.out_dir, "index.md"), "w") as f:
docs.Index(module_to_name, members, libraries,
"../../api_docs/python/").write_markdown_to_file(f)
if __name__ == "__main__":
tf.app.run()
|
