Source Code for Module topo.misc.gendocs

  1  """ 
  2  Topographica-specific changes to the standard pydoc command. 
  3   
  4  Moves generated pydoc HTML files to the docs directory after they are 
  5  created by pydoc.  Intended for use with MAKE, from within the base 
  6  topographica/ directory. 
  7   
  8  The generated index.html file is for the topo/__init__.py file, which 
  9  does not necessarily catalog every .py file in topo/.  To see all 
 10  files, select the 'index' link at the top of one of the html docs. 
 11   
 12  To generate documentation, enter 'make docs' from the base 
 13  topographica/ directory, which will call this file on the Topographica 
 14  sources. 
 15   
 16  From the Makefile (Tabs have been stripped):: 
 17   
 18      cleandocs: 
 19          - rm -r docs 
 20           
 21      docs: topo/*.py 
 22          mkdir -p docs 
 23          ./topographica topo/gendocs.py 
 24          mv docs/topo.__init__.html docs/index.html 
 25   
 26  $Id: gendocs.py 4546 2007-01-04 16:55:33Z jbednar $ 
 27  """ 
 28  __version__='$Revision: 4546 $' 
 29   
 30   
 31  import pydoc, glob, os 
 32  from os.path import isdir 
 33  from re import search, sub 
 34  from copy import copy 
 35   
 36   
 37  TOPO = 'topo'   # Subdirectory with Topographica source 
 38  DOCS = 'doc/Reference_Manual'   # Subdirectory to place Docs 
 39  pydoc.writing = 1 
 40   
 41   
 42 -def _file_list(base_name): 
 43      """ 
 44      Recursively generate a list of files and directories to document. 
 45   
 46      base_name is the relative path to add to directories and files. 
 47      Files that match CVS or __init__.py are ignored. 
 48      """ 
 49      filelist = [f for f in glob.glob(base_name + '/*') 
 50                  if (isdir(f) or search('.py$',f)) 
 51                  and not search('CVS',f) and not search('__init__.py',f)] 
 52      for f in copy(filelist): 
 53          if isdir(f): 
 54              filelist = filelist + _file_list(f) 
 55      return filelist 
 56   
 57   
 58 -def filename_to_docname(f): 
 59      """ 
 60      Convert a path name into the PyDoc filename it will turn into. 
 61   
 62      If the path name ends in a .py, then it is cut off.  If there is no 
 63      extension, the name is assumed to be a directory. 
 64      """ 
 65      f = sub('/','.',f) 
 66      if search('.py$',f): 
 67          f = sub('.py$','.html',f) 
 68      else: 
 69          f = f + '.html' 
 70      return f 
 71   
 72   
 73 -def filename_to_packagename(f): 
 74      """ 
 75      Convert a path name into the Python dotted-notation package name. 
 76   
 77      If the name ends in a .py, then cut it off.  If there is no 
 78      extension, the name is assumed to be a directory, and nothing is done 
 79      other than to replace the '/' with '.' 
 80      """ 
 81      f = sub('/','.',f) 
 82      if search('.py$',f): 
 83          f = sub('.py$','',f) 
 84      return f 
 85   
 86       
 87 -def generate_docs(): 
 88      """ 
 89      Generate all pydoc documentation files within a docs directory under 
 90      ./topographica according to the constant DOCS.  After generation, 
 91      there is an index.html that displays all the modules.  Note that 
 92      if the documentation is being changed, it may be necessary to call 
 93      'make cleandocs' to force a regeneration of documentation.  (We 
 94      don't want to regenerate all the documentation each time a source 
 95      file is changed.) 
 96      """ 
 97      # os.system('rm -rf ' + DOCS + '/*') # Force regeneration 
 98      filelist =  _file_list(TOPO) + [TOPO] 
 99      for i in filelist: 
100          f = filename_to_docname(i) 
101          if not glob.glob(DOCS + '/' + f): 
102              pydoc.writedoc(filename_to_packagename(i)) 
103          if glob.glob(f): 
104              cline = 'mv -f ' + f + ' ' + DOCS + '/' 
105              os.system(cline) 
106          else:                    
107              filelist.remove(i)   
108           
109   
110  if __name__ == '__main__': 
111      generate_docs() 
112