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