Coverage for src/lcdoc/mkdocs/replace/__init_

1"""

2## Markdown Replace

4Allows to add replacements into the markdown source, which are replaced by values given

5by a python module.

7The python module (default is: docs/mdreplace.py) must have a table attribute, either

8dict or callable.

10When callable and kw args in the signature, it will be called with a lot of context, incl. the mkdocs config and the

11current line. Otherwise it will be simply called.

14### Features

16- The replace values can themselves be callable, and if so, are called at replacement

17 time with contextual information:

19 ```python

20 replace(

21 mdblock=md,

22 plugin=self,

23 plugin_file=__file__,

24 config=config,

25 page=page,

26 markdown=markdown,

27 )

28 ```

30- If the callable does not require kw args (e.g. time.ctime) we will not pass them

31- The callable can return a replacement for the whole line, by returning a dict like

32 `{'line': ....}`, i.e. with a "line" key.

33- If the replace values are lists (also as returned by the callable), they will be

34 properly indented as multiline text.

36#### Controlling Replacements Within Fenced Blocks

37 - fenced blocks are omitted EXCEPT:

38 - if the replacement key is specified like this `key:all:` - then even `:key:` in

39 fenced blocks is replaced

41### Config

43- `seperator`: ':' by default.

44 Example: `':curtime:'`, for `{"cur_time": time.ctime}` based replacements.

45- `replacement_file`: when not starting with '/' we'll prefix with docs_dir. Default: "mdreplace.py"

46"""

48import importlib 1 ctxlp

49import inspect 1 ctxlp

50import time 1 ctxlp

51from functools import partial 1 ctxlp

53from mkdocs.config import config_options 1 ctxlp

55from lcdoc.mkdocs.tools import MDPlugin, app, split_off_fenced_blocks, srclink, style 1 ctxlp

56from lcdoc.tools import exists, now, os, read_file, sys 1 ctxlp

58fn_ts = [0] 1 ctxlp

59last_check = [0] 1 ctxlp

61# required if we want to add global stuff like style defs:

62page_markdown_init = {'head': '', 'foot': ''} 1 ctxlp

63page_markdown = {} 1 ctxlp

66def init_page_markdown(table): 1 ctxlp

67 h, f = d.pop(':head:', ''), d.pop(':foot:', '') 1 ctxlp

68 page_markdown_init.update({'head': h, 'foot': f}) 1 ctxlp

70#:docs:built_in_replacements

71class css: 1 ctxlp

73 def csspdf(**kw): 1 ctxlp

74 """

75 No loose headers in pdf print outs via a CSS hack.

77 (page-break-after:avoid not supported in browsers)

78 """

79 s = '''

80 @page { size: A4; }

81 @media print {

82 body { font-family: Arial, Helvetica, sans-serif; }

83 h2,h3,h4 { page-break-inside: avoid; }

84 h2::after,h3::after { content: ""; display: block; height: 200px; margin-bottom: -200px; }

85 h4::after,h5::after { content: ""; display: block; height: 100px; margin-bottom: -100px; }

86 }

87 '''

88 return style(s)

90 # this widens the content on big screens to full width:

91 width = lambda max_width='none', min_width='76.25em': style( 1 ctxlp

92 f'''

93 @media only screen and (min-width: {min_width}) {{

94 .md-main__inner {{

95 max-width: {max_width};

96 }}

97 .md-sidebar--primary {{

98 left: 0;

99 }}

100 .md-sidebar--secondary {{

101 right: 0;

102 margin-left: 0;

103 -webkit-transform: none;

104 transform: none;

105 }}

106 }}

107 '''

108 )

109 fullwidth = width(max_width='none', min_width='76.25em') 1 ctxlp

114class BuiltInReplacements(css): 1 ctxlp

115 # inserts the current time at process start:

116 ctime = time.strftime('%a, %d %b %Y %Hh GMT', time.localtime()) 1 ctxlp

117

118 def pthbase(page, **kw): 1 ctxlp

119 """Relative path to base.

120

121 Add media to docs/img/foo.svg and say: <img src=":pthbase:img/foo.svg" />

122 """

123 l = page.url.split('/')

124 return '../' * (len(l) - 1)

125

126 def srcref(**kw): 1 ctxlp

127 """Finds and links source code

128

129 Examples:

130 :srcref:src/lcdoc/mkdocs/replace/__init__.py

131 :srcref:fn=src/lcdoc/mkdocs/replace/__init__.py

132 :srcref:src/lcdoc/mkdocs/replace/__init__.py=somematch

133 :srcref:fn=src/lcdoc/mkdocs/replace/__init__.py,m=built_in_replacements,t=hardwired

134 """

138 fn = fn[:-1] 1 ctxlp|about/navigation.md

141 if '=' in fn: 2 ctxlp|about/navigation.mdlp|index.md

142 l = fn.split('=') 1 ctxlp|index.md

143 if l[0] == 'fn': 143 ↛ 146line 143 didn't jump to line 146, because the condition on line 143 was never false1 ctxlp|index.md

144 spec = {'fn': l[1]} 1 ctxlp|index.md

145 else:

146 spec = {'fn': l[0], 'm': l[1]}

147 else:

148 spec = {'fn': fn} 1 ctxlp|about/navigation.md

149 else:

152 except Exception as ex:

153 app.error('inline_srclink failed', line=line, page=kw['page'])

154 return {'line': line}

157 spec['t'] = spec['m'] 1 ctxlp|about/navigation.md

158 # if 'changelog' in line: breakpoint() # FIXME BREAKPOINT

161

162#:docs:built_in_replacements

163

164

165d = {} 1 ctxlp

166for k in dir(BuiltInReplacements): 1 ctxlp

167 if not k[0] == '_': 1 ctxlp

168 d[k] = getattr(BuiltInReplacements, k) 1 ctxlp

169built_in_replacements = d 1 ctxlp

170

171

172def load_replacement_file(plugin, config): 1 ctxlp

173 fn = plugin.config['replacement_file'] 1 ctxlp

174 if now() - last_check[0] < 2: 174 ↛ 175line 174 didn't jump to line 175, because the condition on line 174 was never true1 ctxlp

175 return

176 last_check[0] = now() 1 ctxlp

177 try: 1 ctxlp

178 fnmod = fn.rsplit('.py', 1)[0] 1 ctxlp

179 if not fn[0] == '/': 179 ↛ 183line 179 didn't jump to line 183, because the condition on line 179 was never false1 ctxlp

180 fn = config['docs_dir'] + '/' + fn 1 ctxlp

181

182 # cannot reload - have to exec second time. No pdb breaks work then with linenr:

183 if fn_ts[0] and os.stat(fn)[7] != fn_ts[0]: 183 ↛ 184line 183 didn't jump to line 184, because the condition on line 183 was never true1 ctxlp

184 app.info('Change detected - reloading', fn=fn)

185 s = read_file(fn)

186 m = {}

187 exec(s, globals(), m)

188 table = m.get('table')

189 elif plugin.table: 189 ↛ 190line 189 didn't jump to line 190, because the condition on line 189 was never true1 ctxlp

190 return

191 else:

192 # first time we import normally, so we can debug with pdb:

193 app.debug('Try loading replacement file', fn=fn) 1 ctxlp

194 if not exists(fn): 194 ↛ 195line 194 didn't jump to line 195, because the condition on line 194 was never true1 ctxlp

195 return app.info('Will not mdreplace, no lookup file found', fn=fn)

196 sys.path.append(os.path.dirname(fn)) 1 ctxlp

197 mod = importlib.import_module(fnmod) 1 ctxlp

198 table = getattr(mod, 'table', None) 1 ctxlp

199

200 fn_ts[0] = os.stat(fn)[7] 1 ctxlp

201 if not table: 201 ↛ 202line 201 didn't jump to line 202, because the condition on line 201 was never true1 ctxlp

202 app.warning(

203 'Replacement mod requires table attribute', fn=fn, err='no md-replace'

204 )

205 plugin.table = {}

206 return

207 du = table(config) if callable(table) else table 1 ctxlp

208 d = built_in_replacements 1 ctxlp

209 d.update(du) 1 ctxlp

210

211 s = plugin.config['seperator'] 1 ctxlp

212

213 def repl(s, sep=s): 1 ctxlp

214 """If a repl key startwith a bang we replace w/o sep!

215

216 """

217 return s[1:] if s.startswith('!') else f'{sep}{s}{sep}' 1 ctxlp

218

219 init_page_markdown(table=d) 1 ctxlp

220 l = lambda v: v.splitlines() if isinstance(v, str) and '\n' in v else v 1 ctxlp

221 d1 = {k: v for k, v in d.items() if not ':all:' in k} 1 ctxlp

222 d2 = {k: v for k, v in d.items() if ':all:' in k} 1 ctxlp

223 d2 = {k.replace(':all:', ''): v for k, v in d2.items()} 1 ctxlp

224 plugin.table = {repl(k): l(v) for k, v in d1.items()} 1 ctxlp

225 plugin.t_all = {repl(k): l(v) for k, v in d2.items()} 1 ctxlp

226 except Exception as ex:

227 app.warning('replacement table load error', exc=ex)

228 plugin.table = {}

229

230

231def has_kw(func, _h={}): 1 ctxlp

234 r = _h[func] = '**' in str(inspect.signature(func)) 3 ctxlp|about/navigation.mdlp|features/lp/bash/sessions.mdlp|index.md

235 return r 3 ctxlp|about/navigation.mdlp|features/lp/bash/sessions.mdlp|index.md

236

237

238def replace(**kw): 1 ctxlp

246 # if 'plugin_do' in str(l): breakpoint() # FIXME BREAKPOINT

256 else:

257 v = v() # simple funcs like time.ctime

259 stats['multiline'] = stats.get('multiline', 0) + 1

260 ind = ' ' * len(l.split(k, 1)[0])

261 v = ind.join([i for i in v])

263 # a replacement func may deliver the whole new line and also header and

264 # footer:

268 else:

272

273

274class MDReplacePlugin(MDPlugin): 1 ctxlp

275 table = None 1 ctxlp

276 fn_replace = None 1 ctxlp

277 fn_replace_ts = None 1 ctxlp

278

279 config_scheme = (

280 ('seperator', config_options.Type(str, default=':')),

281 ('replacement_file', config_options.Type(str, default='mdreplace.py')),

282 )

283

284 def on_pre_build(self, config): 1 ctxlp

285 # loaded on any change

286 self.table = self.t_all = None 1 ctxlp

287 load_replacement_file(self, config) 1 ctxlp

288

289 def on_page_markdown(self, markdown, page, config, files): 1 ctxlp

290 # a lot of context for the replacement funcs:

291

292 # reset: new page:

297 replace,

298 plugin=self,

299 plugin_file=__file__,

300 config=config,

301 page=page,

302 markdown=markdown,

303 )

305 return

306

309

310 # {'foo:all:': 'bar'} replaces ":foo:" with 'bar' also in fenced blocks:

312 else:

313 lines = markdown.splitlines()

315 return '\n'.join(lines)

316 # w/o :all: we only replace in non fenced blocks:

Coverage for src/lcdoc/mkdocs/replace/init.py: 81.93%

160 statements