experiments/STT-tensorflow
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Fix usage of docs_controls.should_skip.

Browse Source 
`docs_controls` was recently added to allow users to tag objects with `do_not_generate_docs` (it can be used as a decorator). This allows you to skip objects by _identity_, instead of path.

In my initial implementation I checked for the tag in the doc generation step.

This change fixes it to skip objects during the api-crawling step. This is necessary to avoid crawling the internals of all the excluded objects.

To enable this, the `_is_private` method of PublicAPIVisitor needs access to the object, not just the path to it. The changes in `public_api` allow this.

`generate_lib` uses the `_is_private` signature change to inspect the object.

PiperOrigin-RevId: 209587765
This commit is contained in:
Mark Daoust 2018-08-21 06:51:25 -07:00 committed by TensorFlower Gardener
parent eac93feb41
commit ad4018ebb6
2 changed files with 13 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
tensorflow/tools/common/public_api.py
View File

@ -102,9 +102,10 @@ class PublicAPIVisitor(object):
"""Override the default root name of 'tf'.""" """Override the default root name of 'tf'."""
self._root_name = root_name self._root_name = root_name
def _is_private(self, path, name): def _is_private(self, path, name, obj=None):
"""Return whether a name is private.""" """Return whether a name is private."""
# TODO(wicke): Find out what names to exclude. # TODO(wicke): Find out what names to exclude.
del obj # Unused.
return ((path in self._private_map and return ((path in self._private_map and
name in self._private_map[path]) or name in self._private_map[path]) or
(name.startswith('_') and not re.match('__.*__$', name) or (name.startswith('_') and not re.match('__.*__$', name) or
@ -129,7 +130,7 @@ class PublicAPIVisitor(object):
# Remove things that are not visible. # Remove things that are not visible.
for name, child in list(children): for name, child in list(children):
if self._is_private(full_path, name): if self._is_private(full_path, name, child):
children.remove((name, child)) children.remove((name, child))
self._visitor(path, parent, children) self._visitor(path, parent, children)

14
tensorflow/tools/docs/generate_lib.py
View File

@ -112,9 +112,6 @@ def write_docs(output_dir,
_is_free_function(py_object, full_name, parser_config.index)): _is_free_function(py_object, full_name, parser_config.index)):
continue continue
if doc_controls.should_skip(py_object):
continue
sitepath = os.path.join('api_docs/python', sitepath = os.path.join('api_docs/python',
parser.documentation_path(full_name)[:-3]) parser.documentation_path(full_name)[:-3])
@ -298,6 +295,15 @@ def _get_default_do_not_descend_map():
} }
class DocControlsAwareCrawler(public_api.PublicAPIVisitor):
"""A `docs_controls` aware API-crawler."""
def _is_private(self, path, name, obj):
if doc_controls.should_skip(obj):
return True
return super(DocControlsAwareCrawler, self)._is_private(path, name, obj)
def extract(py_modules, def extract(py_modules,
private_map, private_map,
do_not_descend_map, do_not_descend_map,
@ -305,7 +311,7 @@ def extract(py_modules,
"""Extract docs from tf namespace and write them to disk.""" """Extract docs from tf namespace and write them to disk."""
# Traverse the first module. # Traverse the first module.
visitor = visitor_cls(py_modules[0][0]) visitor = visitor_cls(py_modules[0][0])
api_visitor = public_api.PublicAPIVisitor(visitor) api_visitor = DocControlsAwareCrawler(visitor)
api_visitor.set_root_name(py_modules[0][0]) api_visitor.set_root_name(py_modules[0][0])
add_dict_to_dict(private_map, api_visitor.private_map) add_dict_to_dict(private_map, api_visitor.private_map)
add_dict_to_dict(do_not_descend_map, api_visitor.do_not_descend_map) add_dict_to_dict(do_not_descend_map, api_visitor.do_not_descend_map)