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