def build_docs(output_dir, code_url_prefix, search_hints=True): """Build api docs for tensorflow v2. Args: output_dir: A string path, where to put the files. code_url_prefix: prefix for "Defined in" links. search_hints: Bool. Include meta-data search hints at the top of each file. """ # The custom page will be used for raw_ops.md not the one generated above. doc_controls.set_custom_page_content(tf.raw_ops, generate_raw_ops_doc()) # Hide raw_ops from search. for name, obj in tf_inspect.getmembers(tf.raw_ops): if not name.startswith("_"): doc_controls.hide_from_search(obj) _hide_layer_and_module_methods() try: doc_controls.do_not_generate_docs(tf.__operators__) except AttributeError: pass try: doc_controls.do_not_generate_docs(tf.tools) except AttributeError: pass try: doc_controls.do_not_generate_docs(tf.compat.v1.pywrap_tensorflow) except AttributeError: pass try: doc_controls.do_not_generate_docs(tf.pywrap_tensorflow) except AttributeError: pass try: doc_controls.do_not_generate_docs(tf.flags) except AttributeError: pass base_dirs, code_url_prefixes = base_dir.get_base_dirs_and_prefixes( code_url_prefix) doc_generator = generate_lib.DocGenerator( root_title="TensorFlow 2", py_modules=[("tf", tf)], base_dir=base_dirs, search_hints=search_hints, code_url_prefix=code_url_prefixes, site_path=FLAGS.site_path, visitor_cls=TfExportAwareVisitor, private_map=_PRIVATE_MAP) doc_generator.build(output_dir) out_path = pathlib.Path(output_dir) num_files = len(list(out_path.rglob("*"))) if num_files < 2000: raise ValueError("The TensorFlow api should be more than 2500 files" "(found {}).".format(num_files)) expected_path_contents = { "tf/summary/audio.md": "tensorboard/plugins/audio/summary_v2.py", "tf/estimator/DNNClassifier.md": "tensorflow_estimator/python/estimator/canned/dnn.py", "tf/nn/sigmoid_cross_entropy_with_logits.md": "python/ops/nn_impl.py", "tf/keras/Model.md": "tensorflow/python/keras/engine/training.py", "tf/compat/v1/gradients.md": "tensorflow/python/ops/gradients_impl.py", } all_passed = True error_msg_parts = [ 'Some "view source" links seem to be broken, please check:' ] for (rel_path, contents) in expected_path_contents.items(): path = out_path / rel_path if contents not in path.read_text(): all_passed = False error_msg_parts.append(" " + str(path)) if not all_passed: raise ValueError("\n".join(error_msg_parts))
def build_docs(output_dir, code_url_prefix, search_hints): """Build api docs for tensorflow v2. Args: output_dir: A string path, where to put the files. code_url_prefix: prefix for "Defined in" links. search_hints: Bool. Include meta-data search hints at the top of each file. """ if distutils.version.LooseVersion(tf.__version__) >= "2.9": doc_controls.set_deprecated(tf.keras.preprocessing) # The custom page will be used for raw_ops.md not the one generated above. doc_controls.set_custom_page_builder_cls(tf.raw_ops, RawOpsPageInfo) # Hide raw_ops from search. for name, obj in tf_inspect.getmembers(tf.raw_ops): if not name.startswith("_"): doc_controls.hide_from_search(obj) for cls in [ tf.Module, tf.keras.layers.Layer, tf.keras.optimizers.Optimizer ]: doc_controls.decorate_all_class_attributes( decorator=doc_controls.do_not_doc_in_subclasses, cls=cls, skip=["__init__"]) do_not_document = [ "tf.__internal__", "tf.keras.__internal__", "tf.__operators__", "tf.tools", "tf.compat.v1.pywrap_tensorflow", "tf.pywrap_tensorflow", "tf.flags", "tf.batch_mat_mul_v3", "tf.sparse_segment_sum_grad" ] for path in do_not_document: item = tf for part in path.split(".")[1:]: item = getattr(item, part, None) if item is None: continue doc_controls.do_not_generate_docs(item) base_dirs, code_url_prefixes = base_dir.get_base_dirs_and_prefixes( code_url_prefix) doc_generator = generate_lib.DocGenerator( root_title="TensorFlow 2", py_modules=[("tf", tf)], base_dir=base_dirs, search_hints=search_hints, code_url_prefix=code_url_prefixes, site_path=FLAGS.site_path, visitor_cls=TfExportAwareVisitor, private_map=_PRIVATE_MAP, extra_docs=_EXTRA_DOCS) doc_generator.build(output_dir) out_path = pathlib.Path(output_dir) expected_path_contents = { "tf/summary/audio.md": "tensorboard/plugins/audio/summary_v2.py", "tf/estimator/DNNClassifier.md": "tensorflow_estimator/python/estimator/canned/dnn.py", "tf/nn/sigmoid_cross_entropy_with_logits.md": "python/ops/nn_impl.py", "tf/keras/Model.md": "keras/engine/training.py", } all_passed = True error_msg_parts = [ 'Some "view source" links seem to be broken, please check:' ] for (rel_path, contents) in expected_path_contents.items(): path = out_path / rel_path if contents not in path.read_text(): all_passed = False error_msg_parts.append(" " + str(path)) if not all_passed: raise ValueError("\n".join(error_msg_parts)) rejected_path_contents = { "tf/keras/optimizers.md": "keras/optimizers/__init__.py", } all_passed = True error_msg_parts = [ 'Bad "view source" links in generated files, please check:' ] for rel_path, content in rejected_path_contents.items(): path = out_path / rel_path if content in path.read_text(): all_passed = False error_msg_parts.append(" " + str(path)) if not all_passed: raise ValueError("\n".join(error_msg_parts)) num_files = len(list(out_path.rglob("*"))) if num_files < MIN_NUM_FILES_EXPECTED: raise ValueError( f"The TensorFlow api should be more than {MIN_NUM_FILES_EXPECTED} files" f"(found {num_files}).")
def build_docs(output_dir, code_url_prefix, search_hints, gen_report): """Build api docs for tensorflow v2. Args: output_dir: A string path, where to put the files. code_url_prefix: prefix for "Defined in" links. search_hints: Bool. Include meta-data search hints at the top of each file. gen_report: Bool. Generates an API report containing the health of the docstrings of the public API. """ # The custom page will be used for raw_ops.md not the one generated above. doc_controls.set_custom_page_content(tf.raw_ops, generate_raw_ops_doc()) # Hide raw_ops from search. for name, obj in tf_inspect.getmembers(tf.raw_ops): if not name.startswith("_"): doc_controls.hide_from_search(obj) for cls in [ tf.Module, tf.keras.layers.Layer, tf.keras.optimizers.Optimizer ]: doc_controls.decorate_all_class_attributes( decorator=doc_controls.do_not_doc_in_subclasses, cls=cls, skip=["__init__"]) try: doc_controls.do_not_generate_docs(tf.__internal__) except AttributeError: pass try: doc_controls.do_not_generate_docs(tf.keras.__internal__) except AttributeError: pass try: doc_controls.do_not_generate_docs(tf.__operators__) except AttributeError: pass try: doc_controls.do_not_generate_docs(tf.tools) except AttributeError: pass try: doc_controls.do_not_generate_docs(tf.compat.v1.pywrap_tensorflow) except AttributeError: pass try: doc_controls.do_not_generate_docs(tf.pywrap_tensorflow) except AttributeError: pass try: doc_controls.do_not_generate_docs(tf.flags) except AttributeError: pass base_dirs, code_url_prefixes = base_dir.get_base_dirs_and_prefixes( code_url_prefix) doc_generator = generate_lib.DocGenerator( root_title="TensorFlow 2", py_modules=[("tf", tf)], base_dir=base_dirs, search_hints=search_hints, code_url_prefix=code_url_prefixes, site_path=FLAGS.site_path, visitor_cls=TfExportAwareVisitor, private_map=_PRIVATE_MAP, gen_report=gen_report, extra_docs=_EXTRA_DOCS) doc_generator.build(output_dir) if gen_report: return out_path = pathlib.Path(output_dir) expected_path_contents = { "tf/summary/audio.md": "tensorboard/plugins/audio/summary_v2.py", "tf/estimator/DNNClassifier.md": "tensorflow_estimator/python/estimator/canned/dnn.py", "tf/nn/sigmoid_cross_entropy_with_logits.md": "python/ops/nn_impl.py", "tf/keras/Model.md": "keras/engine/training.py", "tf/keras/preprocessing/image/random_brightness.md": "keras_preprocessing/image/affine_transformations.py" } all_passed = True error_msg_parts = [ 'Some "view source" links seem to be broken, please check:' ] for (rel_path, contents) in expected_path_contents.items(): path = out_path / rel_path if contents not in path.read_text(): all_passed = False error_msg_parts.append(" " + str(path)) if not all_passed: raise ValueError("\n".join(error_msg_parts)) rejected_path_contents = { "tf/keras/optimizers.md": "keras/optimizers/__init__.py", } all_passed = True error_msg_parts = [ 'Bad "view source" links in generated files, please check:' ] for rel_path, content in rejected_path_contents.items(): path = out_path / rel_path if content in path.read_text(): all_passed = False error_msg_parts.append(" " + str(path)) if not all_passed: raise ValueError("\n".join(error_msg_parts)) num_files = len(list(out_path.rglob("*"))) if num_files < 2000: raise ValueError("The TensorFlow api should be more than 2000 files" "(found {}).".format(num_files))