X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=doclib%2FSConscript;h=9fbf7d9f0c18a0da6ae43741c8eb5d740271e953;hb=164fe477094d42463722584e527a02379ab5d985;hp=784463831a9d68982ca55f25c9ec6da567c80d8c;hpb=34378cabd0ef59515f60b8e535d50fd5488c84e2;p=senf.git diff --git a/doclib/SConscript b/doclib/SConscript index 7844638..9fbf7d9 100644 --- a/doclib/SConscript +++ b/doclib/SConscript @@ -1,7 +1,123 @@ # -*- python -*- +# +# The documentation generation process is tightly integrated with the +# scons build framework: +# +# * SCons analyzes the Doxyfile's to find all the documentation +# dependencies. This happens in the doxygen builder in +# senfscons/Doxygen.py. +# +# * the doclib/doxy-header.html and/or doclib/doxy-footer.html files +# are regenerated +# +# * If any documentation is out-of-date with respect to it's source +# files, the documentation is regenerated. +# +# * To fix some link errors, the additional 'linklint' and 'fixlinks' +# targets are used +# +# +# 1. Scanning the Doxyfile's +# +# The doxygen builder scans all documentation source files which have +# the text 'doxyfile' in any case in their name. It understands +# @INCLUDE directives and will find all the dependencies of the +# documentation: +# +# * All the source files as selected by INPUT, INPUT_PATTERN, +# RECURSIVE and so on. +# +# * Any referenced tag-files +# +# * Documentation header and/or footer +# +# * The INPUT_FILTER program +# +# * Any included doxygen configuration files +# +# +# 2. Regenerating header and/or footer +# +# If needed, the doxy-header.html and/or doxy-footer.html file will be +# regenerated. The header and/or footer are generated from templates +# using a simple python based templating system called yaptu which is +# included in doclib/. +# +# +# 3. Calling doxygen +# +# The doxygen call itself is quite complex since there is some pre- +# and post-processing going on. We can separate this step into two +# steps +# +# * Building prerequisites (e.g. images) +# +# * The processing done by the Doxygen builder and doclib/doxygen.sh +# +# +# 3.1. Building prerequisites +# +# The prerequisites are images referenced by the documentation. These +# images are mostly generated using the Dia2Png builder. +# +# +# 3.2. The main doxygen build (Doxygen builder) +# +# The Doxygen builder will call the doxygen command to build the +# documentation. +# +# The doxygen command is configured as 'doclib/doxygen.sh' which +# does some additional processing in addition to calling doxygen +# proper +# +# * it sets environment variables depending on command line arguments. +# These variables are then used in the Doxyfile's +# +# * after doxygen is finished, 'installdox' is called to resolve +# tag file references. +# +# * the HTML documentation is post-processed using some sed, tidy, and +# an XSLT template +# +# * a generated tag file is post-processed using an XSLT template +# +# (see doclib/doxygen.sh for more information). The Doxygen +# configuration is set up such, that +# +# * doxygen calls 'doclib/filter.pl' on each source file. This filter +# will strip excess whitespace from the beginning of lines in +# '\code' and '
' blocks. Additionally it will expand all tabs, +# tab width is 8 spaces (there should be no tabs in the source but +# ...) +# +# * doxygen calls 'doclib/dot' to generate the 'dot' images. +# +# * 'doclib/dot' calls 'doclib/dot-munge.pl' on the .dot +# files. dot-munge.pl changes the font and font-size and adds +# line-breaks to long labels +# +# * 'doclib/dot' calls the real dot binary. If the resulting image is +# more than 800 pixels wide, dot is called again, this time using +# the oposite rank direction (top-bottom vs. left-right). The image +# with the smaller width is selected and returned. +# +# +# 4. Fixing broken links +# +# After the documentation has been generated, additional calls first +# to the 'linklint' and then to the 'fixlinks' target will try to fix +# broken links generated by doxygen. First, 'linklint' will call the +# linklint tool to check for broken links in the documentation. +# +# 'fixlinks' is then called which calls 'doclib/fixlinks.py' which +# scans *all* html files, builds an index of all (unique) anchors and +# then fixes the url part of all links with correct anchor but bad +# file name. +# + Import('env') -import SENFSCons +import SENFSCons, datetime, os ########################################################################### @@ -66,7 +182,10 @@ def indices(): if doc.name == "search.idx" ] def writeTemplate(target = None, source = None, env = None): - file(target[0].abspath,"w").write(yaptu.process(str(env['TEMPLATE']), globals(), env.Dictionary())) + file(target[0].abspath,"w").write(processTemplate(env)) + +def processTemplate(env): + return yaptu.process(str(env['TEMPLATE']), globals(), env.Dictionary()) writeTemplate = env.Action(writeTemplate, varlist = [ 'TEMPLATE' ]) @@ -77,6 +196,7 @@ writeTemplate = env.Action(writeTemplate, varlist = [ 'TEMPLATE' ]) EXTRA_MODULES = [ ('Overview', '#/doc/html'), ('Examples', '#/Examples/doc/html'), + ('HowTos', '#/HowTos/doc/html'), ('SENFSCons', '#/senfscons/doc/html') ] HEADER = """ @@ -87,7 +207,7 @@ HEADER = """ @@ -105,15 +225,14 @@ div.tabs ul li.$projectname a { background-color: #EDE497; }@@ -124,11 +243,10 @@ div.tabs ul li.$projectname a { background-color: #EDE497; } {{ for name, path, level in modules():-
-- Open Issues
-- Bug Tracker
-- Browse SVN
-- ChangeLog
-- BerliOS
-- Wiki
- Home
+- Download
+- Wiki
+- BerliOS
+- ChangeLog
+- Browse SVN
+- Bug Tracker
${TITLE}