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)