diff --git a/scripts/generate_json_docs.py b/scripts/generate_json_docs.py index 1d055337ce99c..2c2bd61d5f81c 100644 --- a/scripts/generate_json_docs.py +++ b/scripts/generate_json_docs.py @@ -13,6 +13,7 @@ # limitations under the License. import argparse +import doctest import inspect import json import os @@ -156,26 +157,31 @@ def from_pdoc(cls, element): components = element.refname.split('.') mod = __import__(components[0]) - for comp in components[1:]: mod = getattr(mod, comp) - build_source(mod, method) + # Get method line number. + method.add_source_line(get_source_line_number(mod)) + + # Get method Examples. + examples = get_examples_from_docstring(element.docstring) + if examples: + method.add_example(examples) if element.docstring: if not isinstance(element, pdoc.Class) and element.cls: - cls = element.cls.cls + clas = element.cls.cls elif element.cls: - cls = element.cls + clas = element.cls else: - cls = None + clas = None # Hack for old-style classes - if str(cls)[0] != '<': - cls = '' + if str(clas)[0] != '<': + clas = '' try: - method_info = parse_docstring(element.docstring, cls) + method_info = parse_docstring(element.docstring, clas) except (MethodParsingException, IndexError): return method @@ -183,9 +189,6 @@ def from_pdoc(cls, element): param = Param.from_docstring_section(name, data) method.add_param(param) - if method_info.get('example'): - method.add_example(method_info['example']) - if method_info.get('return'): if len(method_info['return']['type_name']) > 0: type_name = method_info.get('return').get('type_name') @@ -259,26 +262,6 @@ def build_link_from_type(type_name, object_type=None): return type_markup -def build_source(mod, method): - if isinstance(mod, (types.ModuleType, types.ClassType, - types.MethodType, types.FunctionType, - types.TracebackType, types.FrameType, - types.CodeType, types.TypeType)): - - line = inspect.getsourcelines(mod)[1] - source_path = clean_source_path(inspect.getsourcefile(mod)) - - if line: - source_path = source_path + '#L' + str(line) - - method.add_source_line(source_path) - - # Sketchy get examples from method docstring. - examples = [] - for example in examples: - method.add_example(example) - - def build_toc_entry(title, toc_type): return { 'title': title, @@ -302,9 +285,34 @@ def clean_source_path(source): return source_path +def get_examples_from_docstring(doc_str): + examples = doctest.DocTestParser().get_examples(doc_str) + example_str = '' + for example in examples: + example_str += '%s' % example.source + example_str += '%s' % example.want + + return example_str.replace('<', '<').replace('>', '>') + + +def get_source_line_number(mod): + if isinstance(mod, (types.ModuleType, types.ClassType, + types.MethodType, types.FunctionType, + types.TracebackType, types.FrameType, + types.CodeType, types.TypeType)): + + line = inspect.getsourcelines(mod)[1] + source_path = clean_source_path(inspect.getsourcefile(mod)) + + if line: + source_path = source_path + '#L' + str(line) + return source_path + + def process_code_blocks(doc): blocks = [] index = 0 + for line in doc.splitlines(True): if len(blocks) - 1 < index: blocks.append('')