Coverage for src/lcdoc/call_flows/auto_docs.py: 19.39%

1import os, sys, socket, time 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

2import inspect 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

3from lcdoc.call_flows import markdown as MD 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

4from lcdoc.tools import write_file, read_file, exists 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

5 

6T = MD.Mkdocs 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

7h = lambda level, s: '#' * level + ' ' + s 7 ↛ exitline 7 didn't run the lambda on line 72 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

8source = inspect.getsource 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

9 

10auto_gen_cmt = ''' 

11<!-- AUTOMATICALLY GENERATED FILE - DO NOT DIRECTLY EDIT! 

12 

13Direct edits will be gone after next CI build. 

14By: %s@%s (%s) 

15Command Line (see duties.py): 

16 

17 %s 

18--> 

19''' 

20 

21 

22def mark_auto_created(fn): 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

23 from devapp.app import app 

24 

25 if exists(fn): 

26 s = read_file(fn) 

27 else: 

28 s = fn 

29 h = auto_gen_cmt % ( 

30 os.environ.get('USER'), 

31 socket.gethostname(), 

32 time.ctime(), 

33 ' '.join(sys.argv).replace(' -', ' \\\n -'), 

34 ) 

35 s = h.lstrip() + '\n' + s 

36 if exists(fn): 

37 write_file(fn, s) 

38 app.info('Marked content as autocreated') 

39 return s 

40 

41 

42def recurse_into(obj, md, hir=1): 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

43 """obj a module or class""" 

44 code = source(obj) 

45 docu_obj(obj, md, hir, code) 

46 if hir == 1: 

47 md.append('## Use Cases') 

48 hir += 1 

49 # we don't recurse anymore into the module makes no sense too fragmeneted, reading the whole source is better 

50 # return 

51 # cs = classes_by_line_nr(obj, code) 

52 # if cs: 

53 # md.append(MD.header('Classes', hir + 1)) 

54 # for _, c in sorted(cs.items()): 

55 # recurse_into(c, md, hir + 2) 

56 

57 # fs = functions_by_line_nr(obj, code) 

58 # if fs: 

59 # md.append(MD.header('Functions', hir + 1)) 

60 # for _, f in sorted(fs.items()): 

61 # docu_obj(f, md, hir + 2, source(f)) 

62 

63 

64def name(obj): 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

65 n = getattr(obj, '__qualname__', '') or getattr(obj, '__name__') 

66 return n.rsplit('.', 1)[-1] 

67 

68 

69def docu_obj(obj, md, hir, code): 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

70 ds = obj.__doc__ or '' 

71 h, doc = MD.extract_docstr_head(ds) 

72 h = '%s' % h # , name(obj)) 

73 md.append(MD.header(h, hir)) 

74 md.append(doc) 

75 src = T.code('python', code) 

76 md.append(T.closed_admon('%s source code' % name(obj), src)) 

77 

78 

79def module_name(obj): 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

80 return obj.__name__ if inspect.ismodule(obj) else obj.__module__ 

81 

82 

83def in_same_module(obj1, obj2): 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

84 """Don't document stuff outside a containing module""" 

85 return module_name(obj1) == module_name(obj2) 

86 

87 

88def childs(obj, typ): 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

89 cs = [k for k in dir(obj) if not k.startswith('_')] 

90 cs = [getattr(obj, k) for k in cs] 

91 return [c for c in cs if typ(c) and in_same_module(obj, c)] 

92 

93 

94def classes_by_line_nr(obj, code): 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

95 cs = childs(obj, inspect.isclass) 

96 r = {} 

97 for c in cs: 

98 line = code.split('class %s' % c.__name__, 1) 

99 if len(line) == 1: 

100 continue 

101 line = len(line[0].splitlines()) 

102 r[line] = c 

103 return r 

104 

105 

106def functions_by_line_nr(obj, code): 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

107 def filt(f): 

108 return inspect.ismethod(f) or inspect.isfunction(f) 

109 

110 fs = childs(obj, filt) 

111 r = {} 

112 for f in fs: 

113 line = code.split('def %s' % name(f), 1) 

114 if len(line) == 1: 

115 continue 

116 line = len(line[0].splitlines()) 

117 r[line] = f 

118 return r 

119 

120 

121def mod_doc(mod, dest='auto'): 2 ctxlp|features/lp/python/call_flow_logging/index.mdpytest

122 

123 from lcdoc.call_flows.call_flow_logging import autodoc_dir 

124 

125 d = autodoc_dir(mod, dest) 

126 os.makedirs(d, exist_ok=True) 

127 fn = d + '/%s.md' % mod.__name__ 

128 md = [] 

129 recurse_into(mod, md) 

130 c = '\n'.join(md) 

131 write_file(fn, c) 

132 return fn