1#!/usr/bin/env python3 2""" Adds links in the manual pages to tutorials that utilize the functions""" 3 4import os 5 6def processfile(petsc_dir,dir,file,keyre,mdict,uses): 7 '''Find all functions used in the tutorial and add links to the manual page for the function''' 8 #print('Processing '+os.path.join(dir,file)) 9 with open(os.path.join(dir,file),'r') as fd: 10 text = fd.read() 11 found = list(set(keyre.findall(text))) 12 for i in found: 13 if len(uses[i[1:-1]]) < 10: 14 uses[i[1:-1]].append(os.path.join(dir,file)) 15 16def processdir(petsc_dir,dir,keyre,mdict,uses): 17 '''Loop over tutorials, call processfile() on each''' 18 #print('Processing '+dir) 19 for file in os.listdir(dir): 20 if os.path.isfile(os.path.join(dir,file)) and (file.endswith('.c') or file.endswith('.cxx') or file.endswith('.F90')): processfile(petsc_dir,dir,file,keyre,mdict,uses) 21 22def loadmanualpagescit(petsc_dir,build_dir): 23 '''Loads and parses the manualpages.cit file generated by Sowing doctext''' 24 import re 25 mdict = {} 26 PATTERN = re.compile(r'man:\+(.*)\+\+(.*)\+\+\+\+man\+\.\./(.*)#.*') 27 EXCLUDE_PATTERN = re.compile('PetscCall|Petsc[A-Z]*Int|PetscReal|PetscScalar|PetscBool|PetscComplex|PetscErrorCode|SETERR|PetscLog|PETSC_FALSE|PETSC_TRUE') 28 with open(os.path.join(build_dir,'manualpages','manualpages.cit'),'r') as fd: 29 text = fd.read() 30 for line in text.split(): 31 m = re.match(PATTERN, line) 32 # print('Manual page '+m.group(1)+' location '+m.group(3)) 33 if not m: 34 raise RuntimeError('Cannot find PATTERN '+str(PATTERN)+' in manualpages.cit line '+line) 35 if re.match(EXCLUDE_PATTERN,m.group(1)): continue 36 mdict[r' '+m.group(1)+r' '] = m.group(3) 37 mdict[r' '+m.group(1)+r'\)'] = m.group(3) 38 mdict[r' '+m.group(1)+r','] = m.group(3) 39 mdict[r'\('+m.group(1)+r'\('] = m.group(3) 40 # sort to find enclosing names first 41 mdict = dict(sorted(mdict.items(), key=lambda item: len(item[0]), reverse = True)) 42 keyre = re.compile('|'.join(list(mdict.keys()))) 43 uses = {i[1:-1]: [] for i in mdict.keys()} 44 return keyre,mdict,uses 45 46def main(petsc_dir,build_dir): 47 keyre,mdict,uses = loadmanualpagescit(petsc_dir,build_dir) 48 for dirpath, dirnames, filenames in os.walk(os.path.join(petsc_dir,'src'),topdown=True): 49 dirnames[:] = [d for d in dirnames if d not in ['output', 'ftn-custom', 'ftn-auto', 'ftn-mod', 'tests', 'binding']] 50 if dirpath.endswith('tutorials'): 51 processdir(petsc_dir,dirpath,keyre,mdict,uses) 52 53 for i in mdict: 54 if len(uses[i[1:-1]]) > 0: 55 manpage = os.path.join(build_dir,'manualpages',mdict[i]) 56 set_uses = set(uses[i[1:-1]]) 57 uses[i[1:-1]] = [] 58 with open(manpage,'a') as fd: 59 fd.write('\n## Examples\n') 60 for j in set_uses: 61 file = j.replace(petsc_dir+'/','') 62 fd.write('<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/'+file+'.html">'+file+'</A><BR>\n') 63