Source Code for Module ivs.makedoc

  1  #!/usr/bin/env python 
  2  """ 
  3  Generate epydoc documentation of IvS repository and insert images. 
  4   
  5  The documentation will be stored in the subdirectory "doc/html" of the IvS root 
  6  directory (i.e. where this file is located). If previously generated 
  7  documentation exists, it will be overwriten. 
  8   
  9  The main page of the documentation can be found in "doc/html/index.html". 
 10   
 11  Updating the documentation is a simple as rerunning the script, you do not need 
 12  to delete the results from the previous run. 
 13   
 14  For more command-line options, see 
 15   
 16      $:> python makedoc.py -h 
 17  """ 
 18  #-- import necessary modules 
 19  import os 
 20  import subprocess 
 21  import shutil 
 22  import glob 
 23  import webbrowser 
 24  import sys 
 25  import argparse 
 26  from ivs.aux import termtools 
 27   
 28   
 29  #-- skip documentation generation of the following third party modules: 
 30  skip = ['uncertainties','lmfit'] 
 31   
 32  #-- do you want to immediately show the contents in your default webbrowser each 
 33  #   time the documentation is generated (False, 'current tab' or 'new tab')? 
 34  parser = argparse.ArgumentParser(description='Build IvS Python repository documentation') 
 35  parser.add_argument('-o','--open',action='store_true',help='Open documentation in webbrowser after creation') 
 36  parser.add_argument('-v','--verbose',action='store_true',help='Increase output verbosity in Epydoc') 
 37  parser.add_argument('-w','--width',type=int,default=75,help='Width of images (percentage)') 
 38  args = parser.parse_args() 
 39   
 40  #-- remember the current working directory; you can generate the documentation 
 41  #   in any directory if you really want to. 
 42  this_dir = os.path.dirname(os.path.abspath(__file__)) 
 43   
 44  #-- collect all files and directories for which to generate documentation 
 45  output = subprocess.check_output('git ls-files',shell=True) 
 46  alldirs = output.strip().split('\n') 
 47   
 48  #-- we do a quick selection here since we don't want to generate documentation 
 49  #   of third-party modules that are installed alongside the repository 
 50  alldirs = [ff for ff in alldirs if os.path.splitext(ff)[1]=='.py' and not os.path.basename(ff)[:4]=='test'] 
 51  for iskip in skip: 
 52      alldirs = [ff for ff in alldirs if not iskip in ff] 
 53   
 54  #-- build documentation 
 55  cmd = 'epydoc --html '+" ".join(alldirs)+\ 
 56              ' -o doc/html --parse-only --graph all {}'.format('-v' if args.verbose else '') 
 57  print("Building documentation using the command:\n {}".format(cmd)) 
 58  flag = subprocess.call(cmd,shell=True) 
 59   
 60  #-- check if all went well 
 61  if flag: 
 62      print("Could not execute command, do you have epydoc installed?") 
 63      raise SystemExit 
 64   
 65  #-- Epydoc cannot insert images in the HTML code itself, we do this manually. 
 66  #   for this, we look into the HTML code and replace all ]include figure] 
 67  #   occurrences with the HTML code for image insertion. We copy the html file 
 68  #   to a temporary copy, change the html code, save it and replace the old file. 
 69  if not os.path.isdir('doc/images'): 
 70      print("You don't have an image directory; images are not inserted") 
 71      raise SystemExit 
 72   
 73  #-- we can't do everything in a generic way just yet, we first treat the 
 74  #   exception to the general rule. 
 75  '''shutil.move('doc/html/ivs.timeseries.freqanalyse-module.html','doc/html/ivs.timeseries.freqanalyse-module_.html') 
 76  ff = open('doc/html/ivs.timeseries.freqanalyse-module_.html','r') 
 77  oo = open('doc/html/ivs.timeseries.freqanalyse-module.html','w') 
 78  ESC = chr(27) 
 79  for line in ff.readlines(): 
 80      if r'p = pl.ylim(0,0.018)' in line: 
 81          oo.write(line+'\n\n') 
 82          oo.write(r"<center><img src='../images/timeseries_freqanalyse_01.png' alt='[image example]' /></center>"+'\n\n') 
 83          #-- save cursor, remove line, print and reset cursor 
 84          message = 'Added image to ivs.timeseries.freqanalyse' 
 85          termtools.overwrite_line(message) 
 86      else: 
 87          oo.write(line) 
 88  ff.close() 
 89  oo.close() 
 90  os.remove('doc/html/ivs.timeseries.freqanalyse-module_.html')''' 
 91   
 92  #-- now run through all the other ones. We need to explicitly treat line breaks. 
 93  files = sorted(glob.glob('doc/html/*module.html')) 
 94  files+= sorted(glob.glob('doc/html/*class.html')) 
 95  for myfile in files: 
 96      shutil.move(myfile,myfile+'_') 
 97      ff = open(myfile+'_','r') 
 98      oo = open(myfile,'w') 
 99   
100      line_break = False 
101      for line in ff.readlines(): 
102   
103          if ']include figure]' in line or line_break: 
104              filename = line.split(']')[-2].strip() 
105              oo.write(r"<center><img src='../images/{}' alt='[image example]' width='{}%'/></center>".format(filename,args.width)+'\n\n') 
106              #-- save cursor, remove line, print and reset cursor 
107              message = 'Added image {} to {}\r'.format(filename,myfile) 
108              termtools.overwrite_line(message) 
109              oo.write('\n\n') 
110              line_break = False 
111   
112          elif ']include' in line: 
113              line_break = True 
114   
115          else: 
116              oo.write(line) 
117   
118      ff.close() 
119      oo.close() 
120      os.remove(myfile+'_') 
121  #-- that's it! Open the documentation if requested 
122  if os.path.isfile(os.path.join(this_dir,'doc/html/index.html')): 
123      print("HTML documentation is now available in doc/html") 
124  else: 
125      print("Something went wrong during documentation generation") 
126      raise SystemExit 
127  if args.open: 
128      print("Documentation will be opened in your default webbrowser") 
129      webbrowser.open_new_tab('doc/html/index.html') 
130