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) |
---|