[1] | 1 | # Author: Melnychuk Taras |
---|
| 2 | # Contact: fenix@quintagroup.com |
---|
| 3 | # Date: $Date: 2005-11-23 12:35:33 |
---|
| 4 | # Copyright: quintagroup.com |
---|
| 5 | |
---|
| 6 | """ |
---|
| 7 | This tool lets you generate API documentation of any product in Products directory. |
---|
| 8 | It use epydoc for generating API documentation based on docstrings. |
---|
| 9 | This module defines the following classes: |
---|
| 10 | |
---|
| 11 | - `PloneEpydoc`, this is the class that carries responsibility |
---|
| 12 | for generating product documentation. |
---|
| 13 | |
---|
| 14 | Methods: |
---|
| 15 | |
---|
| 16 | - `PloneEpydoc.getProductModules`: return list of all documented modules in product package |
---|
| 17 | - `PloneEpydoc.createDocumentationDirectoryViews`: create file system directory views for generated documentation |
---|
| 18 | - `PloneEpydoc.generate`: generate documentation for product |
---|
| 19 | - `PloneEpydoc.write_object_type`: write pairs 'file':'type' for all generated files in directory contained in 'path' |
---|
| 20 | - `PloneEpydoc.write_content_file_types`: write file type for all files in subdirectories |
---|
| 21 | """ |
---|
| 22 | from Products.CMFCore.DirectoryView import DirectoryView, registerDirectory, createDirectoryView |
---|
| 23 | from Products.Archetypes.public import * |
---|
| 24 | from string import split, index |
---|
| 25 | from os import listdir, walk |
---|
| 26 | from epydoc.cli import cli |
---|
| 27 | from os.path import isdir |
---|
| 28 | import Products |
---|
| 29 | import sys |
---|
| 30 | |
---|
| 31 | from config import * |
---|
| 32 | |
---|
| 33 | schema=BaseFolderSchema |
---|
| 34 | |
---|
| 35 | class PloneEpydoc(BaseFolder): |
---|
| 36 | |
---|
| 37 | schema=schema |
---|
| 38 | archetype_name=ARCHETYPENAME |
---|
| 39 | id=TOOLID |
---|
| 40 | |
---|
| 41 | def __init__(self): |
---|
| 42 | """""" |
---|
| 43 | BaseFolder.__init__(self, self.id) |
---|
| 44 | |
---|
| 45 | def getProductModules(self, path): |
---|
| 46 | """ |
---|
| 47 | return list of all documented modules in product package |
---|
| 48 | Parameters: |
---|
| 49 | |
---|
| 50 | - path: this is absolute path to product |
---|
| 51 | """ |
---|
| 52 | modules = [] |
---|
| 53 | for root, dirs, files in walk(path): |
---|
| 54 | root_list = split(root, '/') |
---|
| 55 | if not 'tests' in root_list: |
---|
| 56 | root_list = root_list[index(root_list, 'Products'):] #XXX FIXME |
---|
| 57 | module_path = '.'.join(root_list) |
---|
| 58 | for f in files[:]: |
---|
| 59 | if f[-3:] == '.py': |
---|
| 60 | f = f[:index(f, '.')] |
---|
| 61 | modules.append(module_path+'.'+f) |
---|
| 62 | return modules |
---|
| 63 | |
---|
| 64 | def createDocumentationDirectoryViews(self, product): |
---|
| 65 | """ |
---|
| 66 | create file system directory views for generated documentation |
---|
| 67 | Parameters: |
---|
| 68 | |
---|
| 69 | - product: product that is documented |
---|
| 70 | """ |
---|
| 71 | try: |
---|
| 72 | registerDirectory(DOCUMENTATION_DIR, GLOBALS) |
---|
| 73 | except OSError, ex: |
---|
| 74 | if ex.errno == 2: # No such file or directory |
---|
| 75 | return |
---|
| 76 | raise |
---|
| 77 | |
---|
| 78 | if not product in self.objectIds(): |
---|
| 79 | createDirectoryView(self, '/'.join([PROJECTNAME,DOCUMENTATION_DIR, product])) |
---|
| 80 | |
---|
| 81 | def generate(self, product, **properties): |
---|
| 82 | """ |
---|
| 83 | generate documentation for product |
---|
| 84 | Parameters: |
---|
| 85 | |
---|
| 86 | - product: product that is documented |
---|
| 87 | - properties: parameters for documentation (docformat, css ....) |
---|
| 88 | """ |
---|
| 89 | sys.argv = [] |
---|
| 90 | modules = [] |
---|
| 91 | sys.argv.append('xxx') |
---|
| 92 | sys.argv.append('--no-private') |
---|
| 93 | sys.argv.append('--noframes') |
---|
| 94 | sys.argv.append('--target='+DOCUMENTATION_PATH+product) |
---|
| 95 | for k in properties.keys(): |
---|
| 96 | sys.argv.append('--'+k+'='+properties[k]) |
---|
| 97 | |
---|
| 98 | modules = self.getProductModules(PRODUCTS_HOME+product) |
---|
| 99 | for m in modules: |
---|
| 100 | sys.argv.append(m) |
---|
| 101 | cli() |
---|
| 102 | self.write_content_file_types(DOCUMENTATION_PATH+product) |
---|
| 103 | self.createDocumentationDirectoryViews(product) |
---|
| 104 | |
---|
| 105 | def write_object_type(self, path, obj_name, obj_type): |
---|
| 106 | """ |
---|
| 107 | write pairs 'file':'type' for all generated files in directory contained in 'path' |
---|
| 108 | Parameters: |
---|
| 109 | |
---|
| 110 | - path: path to product directory |
---|
| 111 | - obj_name: file name |
---|
| 112 | - obj_type: type of file |
---|
| 113 | """ |
---|
| 114 | file = open(path+'/.objects', 'a') |
---|
| 115 | data = obj_name+' : '+obj_type+'\n' |
---|
| 116 | file.write(data) |
---|
| 117 | |
---|
| 118 | def write_content_file_types(self, path): |
---|
| 119 | """ |
---|
| 120 | write file type for all files in subdirectories |
---|
| 121 | Parameters: |
---|
| 122 | |
---|
| 123 | - path: path to product directory |
---|
| 124 | """ |
---|
| 125 | for obj in listdir(path): |
---|
| 126 | if isdir(path+'/'+obj): |
---|
| 127 | dir_path = path+'/'+obj |
---|
| 128 | self.write_content_file_types(dir_path) |
---|
| 129 | |
---|
| 130 | self.write_object_type(path, obj, 'File') |
---|
| 131 | |
---|
| 132 | registerType(PloneEpydoc) |
---|