BaseTools: Use absolute import in Scripts
[mirror_edk2.git] / BaseTools / Scripts / PackageDocumentTools / plugins / EdkPlugins / basemodel / doxygen.py
1 ## @file
2 #
3 # Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR>
4 #
5 # This program and the accompanying materials are licensed and made available
6 # under the terms and conditions of the BSD License which accompanies this
7 # distribution. The full text of the license may be found at
8 # http://opensource.org/licenses/bsd-license.php
9 #
10 # THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 # WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12 #
13
14 from __future__ import print_function
15 from __future__ import absolute_import
16 import os
17
18 from .message import *
19
20 class BaseDoxygeItem:
21 def __init__(self, name, tag=''):
22 self.mName = name
23 self.mTag = tag
24 self.mDescription = ''
25 self.mText = []
26
27 def AddDescription(self, desc):
28 self.mDescription = '%s%s' % (self.mDescription, desc)
29
30 def __str__(self):
31 return '\n'.join(self.mText)
32
33 def Generate(self):
34 """This interface need to be override"""
35
36 class Section(BaseDoxygeItem):
37 def Generate(self):
38 """This interface need to be override"""
39 if len(self.mTag) != 0:
40 self.mText.append(' \section %s %s' % (self.mName, self.mTag))
41 else:
42 self.mText.append(' \section %s' % self.mName)
43
44 self.mText.append(self.mDescription)
45 return self.mText
46
47 class Page(BaseDoxygeItem):
48 def __init__(self, name, tag=None, isSort=True):
49 BaseDoxygeItem.__init__(self, name, tag)
50 self.mSubPages = []
51 self.mIsMainPage = False
52 self.mSections = []
53 self.mIsSort = isSort
54
55 def GetSubpageCount(self):
56 return len(self.mSubPages)
57
58 def AddPage(self, subpage):
59 self.mSubPages.append(subpage)
60 return subpage
61
62 def AddPages(self, pageArray):
63 if pageArray is None:
64 return
65 for page in pageArray:
66 self.AddPage(page)
67
68 def AddSection(self, section):
69 self.mSections.append(section)
70 self.mSections.sort(cmp=lambda x, y: cmp(x.mName.lower(), y.mName.lower()))
71
72 def Generate(self):
73 if self.mIsMainPage:
74 self.mText.append('/** \mainpage %s' % self.mName)
75 self.mIsSort = False
76 else:
77 self.mText.append('/** \page %s %s' % (self.mTag, self.mName))
78
79 if len(self.mDescription) != 0:
80 self.mText.append(self.mDescription)
81 endIndex = len(self.mText)
82
83 self.mSections.sort()
84 for sect in self.mSections:
85 self.mText += sect.Generate()
86
87 endIndex = len(self.mText)
88
89 if len(self.mSubPages) != 0:
90 self.mText.insert(endIndex, "<p> \section content_index INDEX")
91 endIndex = len(self.mText)
92 self.mText.insert(endIndex, '<ul>')
93 endIndex += 1
94 if self.mIsSort:
95 self.mSubPages.sort(cmp=lambda x, y: cmp(x.mName.lower(), y.mName.lower()))
96 for page in self.mSubPages:
97 self.mText.insert(endIndex, '<li>\subpage %s \"%s\" </li>' % (page.mTag, page.mName))
98 endIndex += 1
99 self.mText += page.Generate()
100 self.mText.insert(endIndex, '</ul>')
101 endIndex += 1
102 self.mText.insert(endIndex, ' **/')
103 return self.mText
104
105 class DoxygenFile(Page):
106 def __init__(self, name, file):
107 Page.__init__(self, name)
108 self.mFilename = file
109 self.mIsMainPage = True
110
111 def GetFilename(self):
112 return self.mFilename.replace('/', '\\')
113
114 def Save(self):
115 str = self.Generate()
116 try:
117 f = open(self.mFilename, 'w')
118 f.write('\n'.join(str))
119 f.close()
120 except IOError as e:
121 ErrorMsg ('Fail to write file %s' % self.mFilename)
122 return False
123
124 return True
125
126 doxygenConfigTemplate = """
127 DOXYFILE_ENCODING = UTF-8
128 PROJECT_NAME = %(ProjectName)s
129 PROJECT_NUMBER = %(ProjectVersion)s
130 OUTPUT_DIRECTORY = %(OutputDir)s
131 CREATE_SUBDIRS = YES
132 OUTPUT_LANGUAGE = English
133 BRIEF_MEMBER_DESC = YES
134 REPEAT_BRIEF = YES
135 ABBREVIATE_BRIEF = "The $name class " \\
136 "The $name widget " \\
137 "The $name file " \\
138 is \\
139 provides \\
140 specifies \\
141 contains \\
142 represents \\
143 a \\
144 an \\
145 the
146 ALWAYS_DETAILED_SEC = NO
147 INLINE_INHERITED_MEMB = NO
148 FULL_PATH_NAMES = YES
149 STRIP_FROM_PATH = %(StripPath)s
150 STRIP_FROM_INC_PATH =
151 SHORT_NAMES = YES
152 JAVADOC_AUTOBRIEF = NO
153 QT_AUTOBRIEF = NO
154 MULTILINE_CPP_IS_BRIEF = NO
155 DETAILS_AT_TOP = YES
156 INHERIT_DOCS = YES
157 SEPARATE_MEMBER_PAGES = NO
158 TAB_SIZE = 1
159 ALIASES =
160 OPTIMIZE_OUTPUT_FOR_C = YES
161 OPTIMIZE_OUTPUT_JAVA = NO
162 BUILTIN_STL_SUPPORT = NO
163 CPP_CLI_SUPPORT = NO
164 SIP_SUPPORT = NO
165 DISTRIBUTE_GROUP_DOC = YES
166 SUBGROUPING = YES
167 TYPEDEF_HIDES_STRUCT = NO
168
169 EXTRACT_ALL = YES
170 EXTRACT_PRIVATE = NO
171 EXTRACT_STATIC = NO
172 EXTRACT_LOCAL_CLASSES = NO
173 EXTRACT_LOCAL_METHODS = NO
174 EXTRACT_ANON_NSPACES = NO
175 HIDE_UNDOC_MEMBERS = NO
176 HIDE_UNDOC_CLASSES = NO
177 HIDE_FRIEND_COMPOUNDS = NO
178 HIDE_IN_BODY_DOCS = NO
179 INTERNAL_DOCS = NO
180 CASE_SENSE_NAMES = NO
181 HIDE_SCOPE_NAMES = NO
182 SHOW_INCLUDE_FILES = NO
183 INLINE_INFO = YES
184 SORT_MEMBER_DOCS = YES
185 SORT_BRIEF_DOCS = NO
186 SORT_BY_SCOPE_NAME = YES
187 GENERATE_TODOLIST = YES
188 GENERATE_TESTLIST = YES
189 GENERATE_BUGLIST = YES
190 GENERATE_DEPRECATEDLIST= YES
191 ENABLED_SECTIONS =
192 MAX_INITIALIZER_LINES = 30
193 SHOW_USED_FILES = NO
194 SHOW_DIRECTORIES = NO
195 FILE_VERSION_FILTER =
196
197 QUIET = NO
198 WARNINGS = YES
199 WARN_IF_UNDOCUMENTED = YES
200 WARN_IF_DOC_ERROR = YES
201 WARN_NO_PARAMDOC = YES
202 WARN_FORMAT = "$file:$line: $text "
203 WARN_LOGFILE = %(WarningFile)s
204
205 INPUT = %(FileList)s
206 INPUT_ENCODING = UTF-8
207 FILE_PATTERNS = %(Pattern)s
208 RECURSIVE = NO
209 EXCLUDE = *.svn
210 EXCLUDE_SYMLINKS = NO
211 EXCLUDE_PATTERNS = .svn
212 EXCLUDE_SYMBOLS =
213 EXAMPLE_PATH = %(ExamplePath)s
214 EXAMPLE_PATTERNS = *
215 EXAMPLE_RECURSIVE = NO
216 IMAGE_PATH =
217 INPUT_FILTER =
218 FILTER_PATTERNS =
219 FILTER_SOURCE_FILES = NO
220
221 SOURCE_BROWSER = NO
222 INLINE_SOURCES = NO
223 STRIP_CODE_COMMENTS = YES
224 REFERENCED_BY_RELATION = YES
225 REFERENCES_RELATION = YES
226 REFERENCES_LINK_SOURCE = NO
227 USE_HTAGS = NO
228 VERBATIM_HEADERS = NO
229
230 ALPHABETICAL_INDEX = NO
231 COLS_IN_ALPHA_INDEX = 5
232 IGNORE_PREFIX =
233
234 GENERATE_HTML = YES
235 HTML_OUTPUT = html
236 HTML_FILE_EXTENSION = .html
237 HTML_HEADER =
238 HTML_FOOTER =
239 HTML_STYLESHEET =
240 HTML_ALIGN_MEMBERS = YES
241 GENERATE_HTMLHELP = %(WhetherGenerateHtmlHelp)s
242 HTML_DYNAMIC_SECTIONS = NO
243 CHM_FILE = index.chm
244 HHC_LOCATION =
245 GENERATE_CHI = NO
246 BINARY_TOC = NO
247 TOC_EXPAND = NO
248 DISABLE_INDEX = NO
249 ENUM_VALUES_PER_LINE = 4
250 GENERATE_TREEVIEW = %(WhetherGenerateTreeView)s
251 TREEVIEW_WIDTH = 250
252
253 GENERATE_LATEX = NO
254 LATEX_OUTPUT = latex
255 LATEX_CMD_NAME = latex
256 MAKEINDEX_CMD_NAME = makeindex
257 COMPACT_LATEX = NO
258 PAPER_TYPE = a4wide
259 EXTRA_PACKAGES =
260 LATEX_HEADER =
261 PDF_HYPERLINKS = YES
262 USE_PDFLATEX = YES
263 LATEX_BATCHMODE = NO
264 LATEX_HIDE_INDICES = NO
265
266 GENERATE_RTF = NO
267 RTF_OUTPUT = rtf
268 COMPACT_RTF = NO
269 RTF_HYPERLINKS = NO
270 RTF_STYLESHEET_FILE =
271 RTF_EXTENSIONS_FILE =
272
273 GENERATE_MAN = NO
274 MAN_OUTPUT = man
275 MAN_EXTENSION = .3
276 MAN_LINKS = NO
277
278 GENERATE_XML = NO
279 XML_OUTPUT = xml
280 XML_SCHEMA =
281 XML_DTD =
282 XML_PROGRAMLISTING = YES
283
284 GENERATE_AUTOGEN_DEF = NO
285
286 GENERATE_PERLMOD = NO
287 PERLMOD_LATEX = NO
288 PERLMOD_PRETTY = YES
289 PERLMOD_MAKEVAR_PREFIX =
290
291 ENABLE_PREPROCESSING = YES
292 MACRO_EXPANSION = YES
293 EXPAND_ONLY_PREDEF = YES
294 SEARCH_INCLUDES = YES
295 INCLUDE_PATH = %(IncludePath)s
296 INCLUDE_FILE_PATTERNS = *.h
297 PREDEFINED = %(PreDefined)s
298 EXPAND_AS_DEFINED =
299 SKIP_FUNCTION_MACROS = NO
300
301 TAGFILES =
302 GENERATE_TAGFILE =
303 ALLEXTERNALS = NO
304 EXTERNAL_GROUPS = YES
305 PERL_PATH = /usr/bin/perl
306
307 CLASS_DIAGRAMS = NO
308 MSCGEN_PATH =
309 HIDE_UNDOC_RELATIONS = YES
310 HAVE_DOT = NO
311 CLASS_GRAPH = YES
312 COLLABORATION_GRAPH = YES
313 GROUP_GRAPHS = YES
314 UML_LOOK = NO
315 TEMPLATE_RELATIONS = NO
316 INCLUDE_GRAPH = YES
317 INCLUDED_BY_GRAPH = YES
318 CALL_GRAPH = NO
319 CALLER_GRAPH = NO
320 GRAPHICAL_HIERARCHY = YES
321 DIRECTORY_GRAPH = YES
322 DOT_IMAGE_FORMAT = png
323 DOT_PATH =
324 DOTFILE_DIRS =
325 DOT_GRAPH_MAX_NODES = 50
326 MAX_DOT_GRAPH_DEPTH = 1000
327 DOT_TRANSPARENT = YES
328 DOT_MULTI_TARGETS = NO
329 GENERATE_LEGEND = YES
330 DOT_CLEANUP = YES
331
332 SEARCHENGINE = NO
333
334 """
335 class DoxygenConfigFile:
336 def __init__(self):
337 self.mProjectName = ''
338 self.mOutputDir = ''
339 self.mFileList = []
340 self.mIncludeList = []
341 self.mStripPath = ''
342 self.mExamplePath = ''
343 self.mPattern = ['*.c', '*.h',
344 '*.asm', '*.s', '.nasm', '*.html', '*.dox']
345 self.mMode = 'HTML'
346 self.mWarningFile = ''
347 self.mPreDefined = []
348 self.mProjectVersion = 0.1
349
350 def SetChmMode(self):
351 self.mMode = 'CHM'
352
353 def SetHtmlMode(self):
354 self.mMode = 'HTML'
355
356 def SetProjectName(self, str):
357 self.mProjectName = str
358
359 def SetProjectVersion(self, str):
360 self.mProjectVersion = str
361
362 def SetOutputDir(self, str):
363 self.mOutputDir = str
364
365 def SetStripPath(self, str):
366 self.mStripPath = str
367
368 def SetExamplePath(self, str):
369 self.mExamplePath = str
370
371 def SetWarningFilePath(self, str):
372 self.mWarningFile = str.replace('\\', '/')
373
374 def FileExists(self, path):
375 if path is None:
376 return False
377 if len(path) == 0:
378 return False
379
380 for p in self.mFileList:
381 if path.lower() == p.lower():
382 return True
383
384 return False
385
386 def AddFile(self, path):
387 if path is None:
388 return
389
390 if len(path) == 0:
391 return
392 path = path.replace('\\', '/')
393 if not self.FileExists(path):
394 self.mFileList.append(path)
395
396 def AddIncludePath(self, path):
397 path = path.replace('\\', '/')
398 if path not in self.mIncludeList:
399 self.mIncludeList.append(path)
400
401 def AddPattern(self, pattern):
402 self.mPattern.append(pattern)
403
404 def AddPreDefined(self, macro):
405 self.mPreDefined.append(macro)
406
407 def Generate(self, path):
408 files = ' \\\n'.join(self.mFileList)
409 includes = ' \\\n'.join(self.mIncludeList)
410 patterns = ' \\\n'.join(self.mPattern)
411 if self.mMode.lower() == 'html':
412 sHtmlHelp = 'NO'
413 sTreeView = 'YES'
414 else:
415 sHtmlHelp = 'YES'
416 sTreeView = 'NO'
417
418 text = doxygenConfigTemplate % {'ProjectName':self.mProjectName,
419 'OutputDir':self.mOutputDir,
420 'StripPath':self.mStripPath,
421 'ExamplePath':self.mExamplePath,
422 'FileList':files,
423 'Pattern':patterns,
424 'WhetherGenerateHtmlHelp':sHtmlHelp,
425 'WhetherGenerateTreeView':sTreeView,
426 'IncludePath':includes,
427 'WarningFile':self.mWarningFile,
428 'PreDefined':' '.join(self.mPreDefined),
429 'ProjectVersion':self.mProjectVersion}
430 try:
431 f = open(path, 'w')
432 f.write(text)
433 f.close()
434 except IOError as e:
435 ErrorMsg ('Fail to generate doxygen config file %s' % path)
436 return False
437
438 return True
439
440 ########################################################################
441 # TEST CODE
442 ########################################################################
443 if __name__== '__main__':
444 df = DoxygenFile('Platform Document', 'm:\tree')
445 df.AddPage(Page('Module', 'module'))
446 p = df.AddPage(Page('Library', 'library'))
447 p.AddDescription(desc)
448 p.AddPage(Page('PCD', 'pcds'))
449
450 df.Generate()
451 print(df)