Coverage for src/lcdoc/call_flows/auto_docs.py : 19.39%
Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1import os, sys, socket, time lp|features/lp/python/call_flow_logging/index.mdpytest
2import inspect lp|features/lp/python/call_flow_logging/index.mdpytest
3from lcdoc.call_flows import markdown as MD lp|features/lp/python/call_flow_logging/index.mdpytest
4from lcdoc.tools import write_file, read_file, exists lp|features/lp/python/call_flow_logging/index.mdpytest
6T = MD.Mkdocs lp|features/lp/python/call_flow_logging/index.mdpytest
7h = lambda level, s: '#' * level + ' ' + s 7 ↛ exitline 7 didn't run the lambda on line 7lp|features/lp/python/call_flow_logging/index.mdpytest
8source = inspect.getsource lp|features/lp/python/call_flow_logging/index.mdpytest
10auto_gen_cmt = '''
11<!-- AUTOMATICALLY GENERATED FILE - DO NOT DIRECTLY EDIT!
13Direct edits will be gone after next CI build.
14By: %s@%s (%s)
15Command Line (see duties.py):
17 %s
18-->
19'''
22def mark_auto_created(fn): lp|features/lp/python/call_flow_logging/index.mdpytest
23 from devapp.app import app
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
42def recurse_into(obj, md, hir=1): lp|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)
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))
64def name(obj): lp|features/lp/python/call_flow_logging/index.mdpytest
65 n = getattr(obj, '__qualname__', '') or getattr(obj, '__name__')
66 return n.rsplit('.', 1)[-1]
69def docu_obj(obj, md, hir, code): lp|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))
79def module_name(obj): lp|features/lp/python/call_flow_logging/index.mdpytest
80 return obj.__name__ if inspect.ismodule(obj) else obj.__module__
83def in_same_module(obj1, obj2): lp|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)
88def childs(obj, typ): lp|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)]
94def classes_by_line_nr(obj, code): lp|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
106def functions_by_line_nr(obj, code): lp|features/lp/python/call_flow_logging/index.mdpytest
107 def filt(f):
108 return inspect.ismethod(f) or inspect.isfunction(f)
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
121def mod_doc(mod, dest='auto'): lp|features/lp/python/call_flow_logging/index.mdpytest
123 from lcdoc.call_flow_logging import autodoc_dir
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