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
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
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:
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',
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()
import ast
import collections
import functools
+import itertools
import json
import os
import re
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.
"""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.
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.
# 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 = ['<div itemscope itemtype="%s">' % schema]
+
+ parts.append('<meta itemprop="name" content="%s" />' % self.name)
+ for item in self._content:
+ parts.append('<meta itemprop="property" content="%s"/>' % item)
+
+ parts.extend(['</div>', ''])
+
+ return '\n'.join(parts)
from __future__ import division
from __future__ import print_function
-import itertools
import textwrap
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')
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:
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')
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 = ['<div itemscope itemtype="%s">' % schema]
-
- parts.append('<meta itemprop="name" content="%s" />' % self.name)
- for item in self._content:
- parts.append('<meta itemprop="property" content="%s"/>' % item)
-
- parts.extend(['</div>', '', ''])
-
- return '\n'.join(parts)
projects / platform / upstream / tensorflow.git / commitdiff