X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=doclib%2FSConscript;h=66de21b37c596f442a7eb1246a78f817afa0d7de;hb=5209d7573f53f4b32730833af00668f5c0e56147;hp=cdb9cd689733ffa811468f9b028f7a02e9cd6204;hpb=54fe6b70dd2c783a37f4bbd62a166160adae0e0f;p=senf.git diff --git a/doclib/SConscript b/doclib/SConscript index cdb9cd6..66de21b 100644 --- a/doclib/SConscript +++ b/doclib/SConscript @@ -1,5 +1,155 @@ # -*- python -*- +# Some internal information on how the documentation is generated. All +# this is quite a mess, the complete documentation generation setup is +# in dire need of a complete redesign, but ... +# +# +# 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. +# +# * possibly 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. +# +# * When building the complete documentation ('all_docs'), the +# cross-reference page will be rebuilt if necessary (The global list +# of 'Open Issues'). +# +# * To fix some link errors, the additional 'linlint' 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 dependencies are *not* complete, just adding a new +# subdirectory sadly does not automatically update the header (which +# contains the menu) +# +# The header and/or footer are written 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 tree +# parts +# +# * Building prerequisites (e.g. images) +# +# * The processing done by the Doxygen builder +# +# * Additional processing added by the SENFSCons.Doxygen helper. +# +# +# 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) +# +# * doxygen proper is called +# +# * doxygen is configured in Doxyfile.global to call +# '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 is configured in Doxyfile.global to call '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. +# +# * after doxygen is finished, the list of referenced tag-files is +# checked. For each tag file the directory is found, where the +# documentation is generated (by scanning the Doxyfile which is +# repsonsible for building the tag file). For every tag file, the +# correct 'installdox' command is generated. +# +# * The stamp files are created +# +# +# 3.3. Postprocessing +# +# The following steps are mostly added to work around some stupid +# doxygen problems +# +# * If a tag file is generated, 'senfscons/tagmunge.xsl' is called on the +# tag file. This XSLT stylesheet removes all namespace components +# from the tag file. Without this task, doxygen will completely barf +# when two different documentation parts have members in the same +# namespace. +# +# * All html files are processed by 'doclib/html-munge.xsl'. However, +# since the documentation generated by doxygen is completely invalid +# html we need to preprocess the html files with a simple 'sed' +# script and 'tidy' before 'xsltproc' even accepts the html code. +# +# * We use the generated xml output of doxygen to generate an XML +# fragment for the global cross reference. This fragment is +# generated by 'senfscons/xrefxtract.xslt' +# +# +# 4. Building the global cross-reference +# +# The global cross reference is built from the cross-refernce +# fragments generated for each of the documentation parts and from the +# doxy-header.html/doxy-footer.html files. This conversion is +# controlled by the 'senfscons/xrefhtml.xslt' stylesheet. +# +# +# 5. 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 @@ -77,6 +227,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 +238,7 @@ HEADER = """ @@ -105,13 +256,15 @@ div.tabs ul li.$projectname a { background-color: #EDE497; }@@ -122,11 +275,10 @@ div.tabs ul li.$projectname a { background-color: #EDE497; } {{ for name, path, level in modules():-
-- Open Issues
-- SVN ChangeLog
-- SENF @ BerliOS
-- Wiki
- Home
+- Download
+- Wiki
+- BerliOS
+- ChangeLog
+- Browse SVN
+- Bug Tracker
+- Open Issues
${TITLE}