def test_docs_for_class_should_skip(self):
class Parent(object):
@doc_controls.do_not_doc_inheritable
def a_method(self, arg='default'):
pass
class Child(Parent):
def a_method(self, arg='default'):
pass
index = {
'Child': Child,
'Child.a_method': Child.a_method,
}
visitor = DummyVisitor(index=index, duplicate_of={})
reference_resolver = parser.ReferenceResolver.from_visitor(
visitor=visitor, py_module_names=['tf'])
tree = {
'Child': ['a_method'],
}
parser_config = parser.ParserConfig(
reference_resolver=reference_resolver,
duplicates={},
duplicate_of={},
tree=tree,
index=index,
reverse_index={},
base_dir='/',
code_url_prefix='/')
page_info = parser.docs_for_object(full_name='Child',
py_object=Child,
parser_config=parser_config)
# Make sure the `a_method` is not present
self.assertEmpty(page_info.methods)
def test_docs_for_function(self):
index = {
'test_function': test_function
}
visitor = DummyVisitor(index=index, duplicate_of={})
reference_resolver = parser.ReferenceResolver.from_visitor(
visitor=visitor, py_module_names=['tf'])
tree = {
'': ['test_function']
}
parser_config = parser.ParserConfig(
reference_resolver=reference_resolver,
duplicates={},
duplicate_of={},
tree=tree,
index=index,
reverse_index={},
base_dir='/',
code_url_prefix='/')
page_info = parser.docs_for_object(
full_name='test_function',
py_object=test_function,
parser_config=parser_config)
# Make sure the brief docstring is present
self.assertEqual(
tf_inspect.getdoc(test_function).split('\n')[0], page_info.doc.brief)
# Make sure the extracted signature is good.
self.assertEqual(['unused_arg', "unused_kwarg='default'"],
page_info.signature)
# Make sure this file is contained as the definition location.
self.assertEqual(
os.path.relpath(__file__, '/'), page_info.defined_in.rel_path)
def setUp(self):
super().setUp()
self.known_object = object()
reference_resolver = parser.ReferenceResolver(
duplicate_of={},
is_fragment={
'tfdocs.api_generator.parser.extract_decorators': False
},
py_module_names=[])
self.parser_config = parser.ParserConfig(
reference_resolver=reference_resolver,
duplicates={},
duplicate_of={},
tree={},
index={},
reverse_index={
id(self.known_object):
'location.of.object.in.api',
id(parser.extract_decorators):
'tfdocs.api_generator.parser.extract_decorators',
},
base_dir='/',
code_url_prefix='/')
def test_get_other_member_doc_unknown_class(self):
class A():
"""Class docs"""
pass
a = A()
parser_config = parser.ParserConfig(
reference_resolver=None,
duplicates={},
duplicate_of={},
tree={},
index={},
reverse_index={},
base_dir='/',
code_url_prefix='/')
result = parser._get_other_member_doc(a, parser_config, {})
expected = textwrap.dedent("""\
Instance of `__main__.A`""")
self.assertEqual(expected, result)
def setUp(self):
super(LinterTest, self).setUp()
index = {
'TestClass': TestClass,
'TestClass.__init__': TestClass.__init__,
'TestClass.method_one': TestClass.method_one,
}
tree = {
'TestClass': ['__init__', 'method_one'],
}
reference_resolver = parser.ReferenceResolver.from_visitor(
visitor=DummyVisitor(index=index, duplicate_of={}),
py_module_names=['tf'],
)
self.parser_config = parser.ParserConfig(
reference_resolver=reference_resolver,
duplicates={},
duplicate_of={},
tree=tree,
index=index,
reverse_index={},
base_dir='/',
code_url_prefix='/')
def test_docs_for_function_with_kwargs(self):
index = {
'test_function_with_args_kwargs': test_function_with_args_kwargs
}
visitor = DummyVisitor(index=index, duplicate_of={})
reference_resolver = parser.ReferenceResolver.from_visitor(
visitor=visitor, doc_index={}, py_module_names=['tf'])
tree = {
'': ['test_function_with_args_kwargs']
}
parser_config = parser.ParserConfig(
reference_resolver=reference_resolver,
duplicates={},
duplicate_of={},
tree=tree,
index=index,
reverse_index={},
guide_index={},
base_dir='/',
code_url_prefix='/')
page_info = parser.docs_for_object(
full_name='test_function_with_args_kwargs',
py_object=test_function_with_args_kwargs,
parser_config=parser_config)
# Make sure the brief docstring is present
self.assertEqual(
tf_inspect.getdoc(test_function_with_args_kwargs).split('\n')[0],
page_info.doc.brief)
# Make sure the extracted signature is good.
self.assertEqual(['unused_arg', '*unused_args', '**unused_kwargs'],
page_info.signature)
def test_parse_md_docstring(self):
def test_function_with_fancy_docstring(arg):
"""Function with a fancy docstring.
And a bunch of references: `tf.reference`, another `tf.reference`,
a member `tf.reference.foo`, and a `tf.third`.
Args:
arg: An argument.
Raises:
an exception
Returns:
arg: the input, and
arg: the input, again.
@compatibility(numpy)
NumPy has nothing as awesome as this function.
@end_compatibility
@compatibility(theano)
Theano has nothing as awesome as this function.
Check it out.
@end_compatibility
"""
return arg, arg
class HasOneMember(object):
def foo(self):
pass
duplicate_of = {'tf.third': 'tf.fourth'}
index = {
'tf': test_module,
'tf.fancy': test_function_with_fancy_docstring,
'tf.reference': HasOneMember,
'tf.reference.foo': HasOneMember.foo,
'tf.third': HasOneMember,
'tf.fourth': HasOneMember
}
visitor = DummyVisitor(index=index, duplicate_of=duplicate_of)
reference_resolver = parser.ReferenceResolver.from_visitor(
visitor=visitor, py_module_names=['tf'])
parser_config = parser.ParserConfig(
reference_resolver=reference_resolver,
duplicates={},
duplicate_of={},
tree={},
index=index,
reverse_index={},
base_dir='/',
code_url_prefix='/')
doc_info = parser._parse_md_docstring(
test_function_with_fancy_docstring,
relative_path_to_root='../..',
full_name=None,
parser_config=parser_config)
freeform_docstring = '\n'.join(part
for part in doc_info.docstring_parts
if isinstance(part, str))
self.assertNotIn('@', freeform_docstring)
self.assertNotIn('compatibility', freeform_docstring)
self.assertNotIn('Raises:', freeform_docstring)
title_blocks = [
part for part in doc_info.docstring_parts
if not isinstance(part, str)
]
self.assertLen(title_blocks, 3)
self.assertCountEqual(doc_info.compatibility.keys(),
{'numpy', 'theano'})
self.assertEqual(doc_info.compatibility['numpy'],
'NumPy has nothing as awesome as this function.\n')
def test_docs_for_class(self):
index = {
'TestClass': TestClass,
'TestClass.a_method': TestClass.a_method,
'TestClass.a_property': TestClass.a_property,
'TestClass.ChildClass': TestClass.ChildClass,
'TestClass.static_method': TestClass.static_method,
'TestClass.class_method': TestClass.class_method,
'TestClass.CLASS_MEMBER': TestClass.CLASS_MEMBER,
}
visitor = DummyVisitor(index=index, duplicate_of={})
reference_resolver = parser.ReferenceResolver.from_visitor(
visitor=visitor, py_module_names=['tf'])
tree = {
'TestClass': [
'a_method', 'class_method', 'static_method', 'a_property',
'ChildClass', 'CLASS_MEMBER'
]
}
parser_config = parser.ParserConfig(
reference_resolver=reference_resolver,
duplicates={},
duplicate_of={},
tree=tree,
index=index,
reverse_index={},
base_dir='/',
code_url_prefix='/')
page_info = parser.docs_for_object(full_name='TestClass',
py_object=TestClass,
parser_config=parser_config)
# Make sure the brief docstring is present
self.assertEqual(
inspect.getdoc(TestClass).split('\n')[0], page_info.doc.brief)
# Make sure the method is present
method_infos = {
method_info.short_name: method_info
for method_info in page_info.methods
}
self.assertIs(method_infos['a_method'].py_object, TestClass.a_method)
# Make sure that the signature is extracted properly and omits self.
self.assertEqual(["arg='default'"],
method_infos['a_method'].signature.arguments)
self.assertEqual(method_infos['static_method'].decorators,
['staticmethod'])
self.assertEqual(method_infos['class_method'].decorators,
['classmethod'])
# Make sure the property is present
attrs = page_info.attr_block
self.assertIsInstance(attrs, parser.TitleBlock)
self.assertIn('a_property', [name for name, desc in attrs.items])
# Make sure there is a link to the child class and it points the right way.
self.assertIs(TestClass.ChildClass, page_info.classes[0].py_object)
# Make sure this file is contained as the definition location.
self.assertEqual(os.path.relpath(__file__, '/'),
page_info.defined_in.rel_path)
