xref: /petsc/doc/build_man_examples_links.py (revision e11240658f9b421e9437d18cf1a9227ac7f0a969) 
1#!/usr/bin/env python
2""" Adds links in the manual pages to tutorials that utilize the functions"""
3
4import os
5import errno
6import subprocess
7import shutil
8import argparse
9
10
11'''manexamples:
12	-@base=$$(basename $$(pwd)); \
13        if [ "$${base}" = "tutorials" ] ; then \
14          petsc_dir=$$(realpath ${PETSC_DIR}); LOCDIR=$$(pwd | sed s"?$${petsc_dir}/??"g)/; \
15          for i in ${EXAMPLESALL} foo ; do \
16            if [ "$$i" != "foo" ] ; then \
17              a=`cat $$i | ${MAPNAMES} -map ${LOC}/manualpages/manualpages.cit \
18                   -printmatch-link -o /dev/null| cut -f 2 | cut -d '#' -f 1 |sed -e s~^../~~ | grep \\.md$$ | sort | uniq` ;  \
19              for j in $$a ; do \
20                b=`ls ${LOC}/manualpages/$${j} | grep -v /all/ | cut -f9` ; \
21                l=`grep "^<A HREF=\"PETSC_DOC_OUT_ROOT_PLACEHOLDER.*/tutorials/" $${b} | wc -l`; \
22                if [ $$l -le 10 ] ; then \
23                  if [ $$l -eq 0 ] ; then \
24                    printf "\n## Examples\n" >> $$b; \
25                  fi; \
26                  echo  "<A HREF=\"PETSC_DOC_OUT_ROOT_PLACEHOLDER/XX\">BB</A><BR>" | sed s?XX?$${LOCDIR}$$i.html?g | sed s?BB?$${LOCDIR}$$i?g >> $$b; \
27                fi; \
28              done; \
29            fi; \
30	  done; \
31        fi
32'''
33
34'''
35r = re.compile(".*cat")
36newlist = list(filter(r.match, mylist)) # Read Note below
37'''
38
39
40def processfile(petsc_dir,dir,file,keyre,mdict,counts):
41  '''Find all functions used in the tutorial and add links to the manual page for the function'''
42  #print('Processing '+os.path.join(dir,file))
43  with open(os.path.join(dir,file),'r') as fd:
44    text = fd.read()
45  found = list(set(keyre.findall(text)))
46  for i in found: counts[i] = counts[i]+1
47
48def processdir(petsc_dir,dir,keyre,mdict,counts):
49  '''Loop over tutorials, call processfile() on each'''
50  print('Processing '+dir)
51  for file in os.listdir(dir):
52    if os.path.isfile(os.path.join(dir,file)) and (file.endswith('.c') or file.endswith('.cxx')): processfile(petsc_dir,dir,file,keyre,mdict,counts)
53
54def loadmanualpagescit(loc):
55  '''Loads and parses the manualpages.cit file generated by Sowing doctext'''
56  import re
57  mdict = {}
58  PATTERN = re.compile(r'man:\+(.*)\+\+(.*)\+\+\+\+man\+(.*)#.*')
59  EXCLUDE_PATTERN = re.compile('PetscCall|Petsc[A-Z]*Int|PetscReal|PetscScalar|PetscBool|PetscComplex|PetscErrorCode|SETERR|PetscLog|PETSC_FALSE|PETSC_TRUE')
60  with open(os.path.join(loc,'manualpages','manualpages.cit'),'r') as fd:
61    text = fd.read()
62  for line in  text.split():
63    m = re.match(PATTERN, line)
64    # print('Manual page '+m.group(1)+' location '+m.group(3))
65    if re.match(EXCLUDE_PATTERN,m.group(1)): continue
66    mdict[m.group(1)] = m.group(3)
67  # sort to find enclosing names first
68  mdict = dict(sorted(mdict.items(), key=lambda item: len(item[0]), reverse = True))
69  keyre = re.compile('|'.join(list(mdict.keys())))
70  return keyre,mdict
71
72def main(petsc_dir,loc):
73    keyre,mdict = loadmanualpagescit(loc)
74    counts = dict(zip(mdict.keys(), [0]*len(mdict.keys())))
75    for dirpath, dirnames, filenames in os.walk(os.path.join(petsc_dir,'src'),topdown=True):
76      dirnames[:] = [d for d in dirnames if d not in ['output', 'ftn-custom', 'f90-custom', 'ftn-auto', 'f90-mod', 'tests', 'binding']]
77      if dirpath.endswith('tutorials'):
78        processdir(petsc_dir,dirpath,keyre,mdict,counts)
79    print(counts['VecCreate'])
80
81if __name__ == "__main__":
82   main(os.path.abspath(os.environ['PETSC_DIR']),os.path.abspath(os.environ['LOC']))
83