doclib/SConscript

   1 # -*- python -*-
   2 #
   3 # The documentation generation process is tightly integrated with the
   4 # scons build framework:
   5 #
   6 # * SCons analyzes the Doxyfile's to find all the documentation
   7 #   dependencies. This happens in the doxygen builder in
   8 #   senfscons/Doxygen.py.
   9 #
  10 # * the doclib/doxy-header.html and/or doclib/doxy-footer.html files
  11 #   are regenerated
  12 #
  13 # * If any documentation is out-of-date with respect to it's source
  14 #   files, the documentation is regenerated.
  15 #
  16 # * To fix some link errors, the additional 'linklint' and 'fixlinks'
  17 #   targets are used
  18 #
  19 #
  20 # 1. Scanning the Doxyfile's
  21 #
  22 # The doxygen builder scans all documentation source files which have
  23 # the text 'doxyfile' in any case in their name. It understands
  24 # @INCLUDE directives and will find all the dependencies of the
  25 # documentation:
  26 #
  27 # * All the source files as selected by INPUT, INPUT_PATTERN,
  28 #   RECURSIVE and so on.
  29 #
  30 # * Any referenced tag-files
  31 #
  32 # * Documentation header and/or footer
  33 #
  34 # * The INPUT_FILTER program
  35 #
  36 # * Any included doxygen configuration files
  37 #
  38 #
  39 # 2. Regenerating header and/or footer
  40 #
  41 # If needed, the doxy-header.html and/or doxy-footer.html file will be
  42 # regenerated. The dependencies are *not* complete, just adding a new
  43 # subdirectory sadly does not automatically update the header (which
  44 # contains the menu)
  45 #
  46 # The header and/or footer are written are generated from templates
  47 # using a simple python based templating system called yaptu which is
  48 # included in doclib/.
  49 #
  50 #
  51 # 3. Calling doxygen
  52 #
  53 # The doxygen call itself is quite complex since there is some pre-
  54 # and post-processing going on. We can separate this step into two
  55 # steps
  56 #
  57 # * Building prerequisites (e.g. images)
  58 #
  59 # * The processing done by the Doxygen builder and doclib/doxygen.sh
  60 #
  61 #
  62 # 3.1. Building prerequisites
  63 #
  64 # The prerequisites are images referenced by the documentation. These
  65 # images are mostly generated using the Dia2Png builder.
  66 #
  67 #
  68 # 3.2. The main doxygen build (Doxygen builder)
  69 #
  70 # The Doxygen builder will call the doxygen command to build the
  71 # documentation.
  72 #
  73 # The doxygen command is configured as 'doclib/doxygen.sh' which
  74 # does some additional processing in addition to calling doxygen
  75 # proper
  76 #
  77 # * it sets environment variables depending on command line arguments.
  78 #   These variables are then used in the Doxyfile's
  79 #
  80 # * after doxygen is finished, 'installdox' is called to resolve
  81 #   tag file references.
  82 #
  83 # * the HTML documentation is post-processed using some sed, tidy, and
  84 #   an XSLT template
  85 #
  86 # * a generated tag file is post-processed using an XSLT template
  87 #
  88 # (see doclib/doxygen.sh for more information). The Doxygen
  89 # configuration is set up such, that
  90 #
  91 # * doxygen calls 'doclib/filter.pl' on each source file. This filter
  92 #   will strip excess whitespace from the beginning of lines in
  93 #   '\code' and '<pre>' blocks. Additionally it will expand all tabs,
  94 #   tab width is 8 spaces (there should be no tabs in the source but
  95 #   ...)
  96 #
  97 # * doxygen calls 'doclib/dot' to generate the 'dot' images.
  98 #
  99 # * 'doclib/dot' calls 'doclib/dot-munge.pl' on the .dot
 100 #    files. dot-munge.pl changes the font and font-size and adds
 101 #    line-breaks to long labels
 102 #
 103 # * 'doclib/dot' calls the real dot binary. If the resulting image is
 104 #   more than 800 pixels wide, dot is called again, this time using
 105 #   the oposite rank direction (top-bottom vs. left-right). The image
 106 #   with the smaller width is selected and returned.
 107 #
 108 #
 109 # 4. Fixing broken links
 110 #
 111 # After the documentation has been generated, additional calls first
 112 # to the 'linklint' and then to the 'fixlinks' target will try to fix
 113 # broken links generated by doxygen. First, 'linklint' will call the
 114 # linklint tool to check for broken links in the documentation.
 115 #
 116 # 'fixlinks' is then called which calls 'doclib/fixlinks.py' which
 117 # scans *all* html files, builds an index of all (unique) anchors and
 118 # then fixes the url part of all links with correct anchor but bad
 119 # file name.
 120 #
 121
 122
 123 Import('env')
 124 import SENFSCons
 125
 126 ###########################################################################
 127
 128 import yaptu
 129
 130 def modules():
 131     # Naja ... etwas rumgehackt aber was solls ...
 132     global EXTRA_MODULES
 133     mods = {}
 134     pathbase = len(env.Dir('#').abspath)+1
 135     for module in env.Alias('all_docs')[0].sources:
 136         if module.name != 'html.stamp' : continue
 137         mods[module.dir.dir.dir.abspath] = [ module.dir.dir.dir.name,
 138                                              module.dir.abspath[pathbase:],
 139                                              0 ]
 140
 141     rv = []
 142     keys = mods.keys()
 143     keys.sort()
 144     for mod in keys:
 145         i = 0
 146         while i < len(rv):
 147             if len(rv[i]) > pathbase and mod.startswith(rv[i] + '/'):
 148                 level = mods[rv[i]][2] + 1
 149                 i += 1
 150                 while i < len(rv) and mods[rv[i]][2] >= level:
 151                     i += 1
 152                 rv[i:i] = [ mod ]
 153                 mods[mod][2] = level
 154                 break
 155             i += 1
 156         if i == len(rv):
 157             rv.append(mod)
 158
 159     for mod in keys:
 160         if mods[mod][2] == 0:
 161             mods[mod][0] = 'lib' + mods[mod][0]
 162
 163     n = 0
 164     for name,path in EXTRA_MODULES:
 165         path = env.Dir(path).dir.dir.abspath
 166         i = 0
 167         while i < len(rv):
 168             if rv[i] == path:
 169                 mods[rv[i]][0] = name
 170                 m = 1
 171                 while i+m < len(rv) and mods[rv[i+m]][2] > mods[rv[i]][2]:
 172                     m += 1
 173                 rv[n:n] = rv[i:i+m]
 174                 rv[i+m:i+2*m] = []
 175                 i += m
 176                 n += m
 177             else:
 178                 i += 1
 179
 180     return ( tuple(mods[mod]) for mod in rv )
 181
 182 def indices():
 183     ix = len(env.Dir('#').abspath)+1
 184     return [ doc.dir.abspath[ix:]
 185              for doc in env.Alias('all_docs')[0].sources
 186              if doc.name == "search.idx" ]
 187
 188 def writeTemplate(target = None, source = None, env = None):
 189     file(target[0].abspath,"w").write(yaptu.process(str(env['TEMPLATE']), globals(), env.Dictionary()))
 190
 191 writeTemplate = env.Action(writeTemplate, varlist = [ 'TEMPLATE' ])
 192
 193 ###########################################################################
 194
 195 # Extra documentation modules which are handled (named) different from
 196 # library modules
 197 EXTRA_MODULES = [
 198     ('Overview', '#/doc/html'),
 199     ('Examples', '#/Examples/doc/html'),
 200     ('HowTos', '#/HowTos/doc/html'),
 201     ('SENFSCons', '#/senfscons/doc/html') ]
 202
 203 HEADER = """<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 204 <html>
 205 <head>
 206 <title>$title</title>
 207 <link href="@TOPDIR@/doc/html/doxygen.css" rel="stylesheet" type="text/css">
 208 <link href="@TOPDIR@/doclib/senf.css" rel="stylesheet" type="text/css">
 209 <link rel="shortcut icon" href="@TOPDIR@/doclib/favicon.ico">
 210 <style type="text/css">
 211 div.tabs li.$projectname a { background-color: #EDE497; }
 212 </style>
 213 </head>
 214 <body>
 215
 216 <div id="head">
 217   <div id="title">
 218     <div id="title2">
 219       <div id="search">
 220         <form action="@TOPDIR@/doclib/search.php" method="get">
 221           Search: <input type="text" name="query" size="20" accesskey="s"/>
 222         </form>
 223       </div>
 224       <h1>SENF Extensible Network Framework</h1>
 225     </div>
 226   </div>
 227   <div id="subtitle">
 228     <ul>
 229       <li><a href="@TOPDIR@/doc/html/index.html">Home</a></li>
 230       <li><a class="ext" href="http://satext.fokus.fraunhofer.de/senf/debian">Download</a></li>
 231       <li><a class="ext" href="http://openfacts2.berlios.de/wikien/index.php/BerliosProject:SENF_Network_Framework">Wiki</a></li>
 232       <li><a class="ext" href="http://developer.berlios.de/projects/senf">BerliOS</a></li>
 233       <li><a class="ext" href="http://svn.berlios.de/wsvn/senf/?op=log&rev=0&sc=0&isdir=1">ChangeLog</a></li>
 234       <li><a class="ext" href="http://svn.berlios.de/viewcvs/senf/trunk/">Browse SVN</a></li>
 235       <li><a class="ext" href="http://developer.berlios.de/bugs/?group_id=7489">Bug Tracker</a></li>
 236       <li><a href="@TOPDIR@/doc/html/xref.html">Open Issues</a></li>
 237     </ul>
 238   </div>
 239 </div>
 240
 241 <div id="content1">
 242   <div id="content2">
 243     <div class="tabs menu">
 244       <ul>
 245 {{      for name, path, level in modules():
 246           <li class="${name} level${level}"><a href="@TOPDIR@/${path}/index.html">${name}</a></li>
 247 }}
 248         <li class="glossary level0"><a href="@TOPDIR@/doc/html/glossary.html">Glossary</a></li>
 249       </ul>
 250     </div>"""
 251
 252 FOOTER = """<hr style="width:0px;border:none;clear:both;margin:0;padding:0" />
 253   </div>
 254 </div>
 255 <div id="footer">
 256   <span>
 257     <a href="mailto:senf-dev@lists.berlios.de">Contact: senf-dev@lists.berlios.de</a> |
 258     Copyright &copy; 2006 Fraunhofer Gesellschaft, SatCom, Stefan Bund
 259   </span>
 260 </div>
 261 </body></html>"""
 262
 263 SEARCH_PHP="""
 264 <?php include 'search_functions.php'; ?>
 265 <?php search(); ?>"""
 266
 267 SEARCH_PATHS_PHP="""<?php
 268 function paths() {
 269   return array(
 270 {{  for index in indices():
 271       "../${index}/",
 272 }}
 273   );
 274 }
 275 ?>"""
 276
 277 env.Command('doxy-header.html', 'SConscript', writeTemplate,
 278             TEMPLATE = Literal(HEADER),
 279             TITLE = "Documentation and API reference")
 280 env.Command('doxy-footer.html', 'SConscript', writeTemplate,
 281             TEMPLATE = Literal(FOOTER))
 282 env.Alias('all_docs',
 283           env.Command('search.php', [ 'html-munge.xsl', 'SConscript' ],
 284                       [ writeTemplate,
 285                         'xsltproc --nonet --html --stringparam topdir .. -o - $SOURCE $TARGET 2>/dev/null'
 286                             + "| sed"
 287                             +   r" -e 's/\[\[/<?/g' -e 's/\]\]/?>/g'"
 288                             +   r" -e 's/\$$projectname/Overview/g'"
 289                             +   r" -e 's/\$$title/Search results/g'"
 290                             +       "> ${TARGETS[0]}.tmp",
 291                         'mv ${TARGET}.tmp ${TARGET}' ],
 292                       TEMPLATE = Literal(HEADER
 293                                          + SEARCH_PHP.replace('<?','[[').replace('?>',']]')
 294                                          + FOOTER),
 295                       TITLE = "Search results"))
 296 env.Alias('all_docs',
 297           env.Command('search_paths.php', 'SConscript', writeTemplate,
 298                       TEMPLATE = Literal(SEARCH_PATHS_PHP)))
 299
 300 env.Alias('install_all',
 301           env.Install( '$DOCINSTALLDIR/doclib', [ 'favicon.ico',
 302                                                   'logo-head.png',
 303                                                   'search.php',
 304                                                   'search_functions.php',
 305                                                   'search_paths.php',
 306                                                   'senf.css' ] ))
 307
 308 env.Clean('all', 'doxy-header.html') # I should not need this but I do ...
 309 env.Clean('all_docs', 'doxy-header.html') # I should not need this but I do ...