From ee303929b18745e7892d872ceac46c326a32ea93 Mon Sep 17 00:00:00 2001 From: Mark Daoust Date: Wed, 23 May 2018 09:59:25 -0700 Subject: [PATCH] Add a "--no_search_hints" flag to the api-docs generator. PiperOrigin-RevId: 197742114 --- tensorflow/tools/docs/generate_lib.py | 25 +++++++++++-- tensorflow/tools/docs/parser.py | 60 +++++++++++++++++++++++++++++++ tensorflow/tools/docs/pretty_docs.py | 66 ++--------------------------------- 3 files changed, 85 insertions(+), 66 deletions(-) diff --git a/tensorflow/tools/docs/generate_lib.py b/tensorflow/tools/docs/generate_lib.py index 111d54d..853ec61 100644 --- a/tensorflow/tools/docs/generate_lib.py +++ b/tensorflow/tools/docs/generate_lib.py @@ -50,7 +50,11 @@ def _is_free_function(py_object, full_name, index): return True -def write_docs(output_dir, parser_config, yaml_toc, root_title='TensorFlow'): +def write_docs(output_dir, + parser_config, + yaml_toc, + root_title='TensorFlow', + search_hints=True): """Write previously extracted docs to disk. Write a docs page for each symbol included in the indices of parser_config to @@ -66,6 +70,8 @@ def write_docs(output_dir, parser_config, yaml_toc, root_title='TensorFlow'): indices. yaml_toc: Set to `True` to generate a "_toc.yaml" file. root_title: The title name for the root level index.md. + search_hints: (bool) include meta-data search hints at the top of each + output file. Raises: ValueError: if `output_dir` is not an absolute path @@ -134,7 +140,13 @@ def write_docs(output_dir, parser_config, yaml_toc, root_title='TensorFlow'): if not os.path.exists(directory): os.makedirs(directory) # This function returns raw bytes in PY2 or unicode in PY3. - text = pretty_docs.build_md_page(page_info) + if search_hints: + content = [page_info.get_metadata_html()] + else: + content = [''] + + content.append(pretty_docs.build_md_page(page_info)) + text = '\n'.join(content) if six.PY3: text = text.encode('utf-8') with open(path, 'wb') as f: @@ -467,6 +479,12 @@ class DocGenerator(object): self._do_not_descend_map = _get_default_do_not_descend_map() self.yaml_toc = True + self.argument_parser.add_argument( + '--no_search_hints', + dest='search_hints', + action='store_false', + default=True) + def add_output_dir_argument(self): self.argument_parser.add_argument( '--output_dir', @@ -553,7 +571,8 @@ class DocGenerator(object): output_dir, parser_config, yaml_toc=self.yaml_toc, - root_title=root_title) + root_title=root_title, + search_hints=getattr(flags, 'search_hints', True)) _other_docs(flags.src_dir, flags.output_dir, reference_resolver) parser_config.reference_resolver.log_errors() diff --git a/tensorflow/tools/docs/parser.py b/tensorflow/tools/docs/parser.py index fb0bd2c..7363e4f 100644 --- a/tensorflow/tools/docs/parser.py +++ b/tensorflow/tools/docs/parser.py @@ -21,6 +21,7 @@ from __future__ import print_function import ast import collections import functools +import itertools import json import os import re @@ -906,6 +907,9 @@ class _FunctionPageInfo(object): def add_decorator(self, dec): self._decorators.append(dec) + def get_metadata_html(self): + return _Metadata(self.full_name).build_html() + class _ClassPageInfo(object): """Collects docs for a class page. @@ -1099,6 +1103,14 @@ class _ClassPageInfo(object): """Returns a list of `_LinkInfo` pointing to any nested classes.""" return self._classes + def get_metadata_html(self): + meta_data = _Metadata(self.full_name) + for item in itertools.chain(self.classes, self.properties, self.methods, + self.other_members): + meta_data.append(item) + + return meta_data.build_html() + def _add_class(self, short_name, full_name, obj, doc, url): """Adds a `_LinkInfo` for a nested class to `classes` list. @@ -1330,6 +1342,16 @@ class _ModulePageInfo(object): self._other_members.append( _OtherMemberInfo(short_name, full_name, obj, doc)) + def get_metadata_html(self): + meta_data = _Metadata(self.full_name) + + # Objects with their own pages are not added to the matadata list for the + # module, the module only has a link to the object page. No docs. + for item in self.other_members: + meta_data.append(item) + + return meta_data.build_html() + def collect_docs_for_module(self, parser_config): """Collect information necessary specifically for a module's doc page. @@ -1656,3 +1678,41 @@ def generate_global_index(library_name, index, reference_resolver): # TODO(markdaoust): use a _ModulePageInfo -> prety_docs.build_md_page() return '\n'.join(lines) + + +class _Metadata(object): + """A class for building a page's Metadata block. + + Attributes: + name: The name of the page being described by the Metadata block. + """ + + def __init__(self, name): + """Creates a Metadata builder. + + Args: + name: The name of the page being described by the Metadata block. + """ + self.name = name + self._content = [] + + def append(self, item): + """Adds an item from the page to the Metadata block. + + Args: + item: The parsed page section to add. + """ + self._content.append(item.short_name) + + def build_html(self): + """Returns the Metadata block as an Html string.""" + schema = 'http://developers.google.com/ReferenceObject' + parts = ['
' % schema] + + parts.append('' % self.name) + for item in self._content: + parts.append('' % item) + + parts.extend(['
', '']) + + return '\n'.join(parts) diff --git a/tensorflow/tools/docs/pretty_docs.py b/tensorflow/tools/docs/pretty_docs.py index 55ab5bd..63d4fef 100644 --- a/tensorflow/tools/docs/pretty_docs.py +++ b/tensorflow/tools/docs/pretty_docs.py @@ -27,7 +27,6 @@ from __future__ import absolute_import from __future__ import division from __future__ import print_function -import itertools import textwrap @@ -58,8 +57,7 @@ def build_md_page(page_info): def _build_function_page(page_info): """Given a FunctionPageInfo object Return the page as an md string.""" - parts = [_Metadata(page_info.full_name).build_html()] - parts.append('# %s\n\n' % page_info.full_name) + parts = ['# %s\n\n' % page_info.full_name] if len(page_info.aliases) > 1: parts.append('### Aliases:\n\n') @@ -83,17 +81,7 @@ def _build_function_page(page_info): def _build_class_page(page_info): """Given a ClassPageInfo object Return the page as an md string.""" - meta_data = _Metadata(page_info.full_name) - for item in itertools.chain( - page_info.classes, - page_info.properties, - page_info.methods, - page_info.other_members): - meta_data.append(item) - - parts = [meta_data.build_html()] - - parts.append('# {page_info.full_name}\n\n'.format(page_info=page_info)) + parts = ['# {page_info.full_name}\n\n'.format(page_info=page_info)] parts.append('## Class `%s`\n\n' % page_info.full_name.split('.')[-1]) if page_info.bases: @@ -186,17 +174,7 @@ def _build_class_page(page_info): def _build_module_page(page_info): """Given a ClassPageInfo object Return the page as an md string.""" - meta_data = _Metadata(page_info.full_name) - - # Objects with their own pages are not added to the matadata list for the - # module, as the only thing on the module page is a link to the object's page. - for item in page_info.other_members: - meta_data.append(item) - - parts = [meta_data.build_html()] - - parts.append( - '# Module: {full_name}\n\n'.format(full_name=page_info.full_name)) + parts = ['# Module: {full_name}\n\n'.format(full_name=page_info.full_name)] if len(page_info.aliases) > 1: parts.append('### Aliases:\n\n') @@ -317,41 +295,3 @@ def _build_function_details(function_details): parts.append(''.join(sub)) return '\n'.join(parts) - - -class _Metadata(object): - """A class for building a page's Metadata block. - - Attributes: - name: The name of the page being described by the Metadata block. - """ - - def __init__(self, name): - """Create a Metadata builder. - - Args: - name: The name of the page being described by the Metadata block. - """ - self.name = name - self._content = [] - - def append(self, item): - """Add an item from the page to the Metadata block. - - Args: - item: The parsed page section to add. - """ - self._content.append(item.short_name) - - def build_html(self): - """Return the Metadata block as an Html string.""" - schema = 'http://developers.google.com/ReferenceObject' - parts = ['
' % schema] - - parts.append('' % self.name) - for item in self._content: - parts.append('' % item) - - parts.extend(['
', '', '']) - - return '\n'.join(parts) -- 2.7.4