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)