Newer
Older
# 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:
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
#
# * 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
# '<pre>' 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.
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
#
# * 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
###########################################################################
import yaptu
def modules():
# Naja ... etwas rumgehackt aber was solls ...
global EXTRA_MODULES
mods = {}
for module in env.Alias('all_docs')[0].sources:
if module.name != 'html.stamp' : continue
mods[module.dir.dir.dir.abspath] = [ module.dir.dir.dir.name,
module.dir.abspath[pathbase:],
0 ]
rv = []
keys = mods.keys()
keys.sort()
for mod in keys:
i = 0
while i < len(rv):
level = mods[rv[i]][2] + 1
i += 1
while i < len(rv) and mods[rv[i]][2] >= level:
i += 1
rv[i:i] = [ mod ]
mods[mod][2] = level
break
i += 1
if i == len(rv):
rv.append(mod)
for mod in keys:
if mods[mod][2] == 0:
mods[mod][0] = 'lib' + mods[mod][0]
n = 0
for name,path in EXTRA_MODULES:
path = env.Dir(path).dir.dir.abspath
i = 0
while i < len(rv):
if rv[i] == path:
mods[rv[i]][0] = name
m = 1
while i+m < len(rv) and mods[rv[i+m]][2] > mods[rv[i]][2]:
m += 1
rv[n:n] = rv[i:i+m]
rv[i+m:i+2*m] = []
i += m
n += m
else:
i += 1
return ( tuple(mods[mod]) for mod in rv )
def indices():
ix = len(env.Dir('#').abspath)+1
return [ doc.dir.abspath[ix:]
for doc in env.Alias('all_docs')[0].sources
if doc.name == "search.idx" ]
def writeTemplate(target = None, source = None, env = None):
file(target[0].abspath,"w").write(source[0].read())
writeTemplate = env.Action(writeTemplate, varlist = [ 'TEMPLATE' ])
###########################################################################
# Extra documentation modules which are handled (named) different from
# library modules
EXTRA_MODULES = [
('Overview', '#/doc/html'),
('Examples', '#/Examples/doc/html'),
HEADER = """<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>$title</title>
<link href="@TOPDIR@/doc/html/doxygen.css" rel="stylesheet" type="text/css">
<link href="@TOPDIR@/doclib/senf.css" rel="stylesheet" type="text/css">
<style type="text/css">
g0dil
committed
div.tabs li.$projectname a { background-color: #EDE497; }
</style>
</head>
<body>
<div id="head">
<div id="title">
<div id="title2">
<div id="search">
<form action="@TOPDIR@/doclib/search.php" method="get">
Search: <input type="text" name="query" size="20" accesskey="s"/>
</form>
</div>
<h1>SENF Extensible Network Framework</h1>
</div>
<div id="subtitle">
<ul>
<li><a href="@TOPDIR@/doc/html/index.html">Home</a></li>
<li><a class="ext" href="ftp://ftp.berlios.de/pub/senf/">Download</a></li>
<li><a class="ext" href="http://openfacts2.berlios.de/wikien/index.php/BerliosProject:SENF_Network_Framework">Wiki</a></li>
<li><a class="ext" href="http://developer.berlios.de/projects/senf">BerliOS</a></li>
<li><a class="ext" href="http://svn.berlios.de/wsvn/senf/?op=log&rev=0&sc=0&isdir=1">ChangeLog</a></li>
<li><a class="ext" href="http://svn.berlios.de/viewcvs/senf/trunk/">Browse SVN</a></li>
<li><a class="ext" href="http://developer.berlios.de/bugs/?group_id=7489">Bug Tracker</a></li>
<li><a href="@TOPDIR@/doc/html/xref.html">Open Issues</a></li>
</ul>
</div>
</div>
<div id="content1">
<div id="content2">
<div class="tabs menu">
<ul>
{{ for name, path, level in modules():
<li class="${name} level${level}"><a href="@TOPDIR@/${path}/index.html">${name}</a></li>
g0dil
committed
<li class="glossary level0"><a href="@TOPDIR@/doc/html/glossary.html">Glossary</a></li>
</ul>
</div>"""
FOOTER = """<hr style="width:0px;border:none;clear:both;margin:0;padding:0" />
</div>
</div>
<div id="footer">
<span>
<a href="mailto:senf-dev@lists.berlios.de">Contact: senf-dev@lists.berlios.de</a> |
Copyright © 2006 Fraunhofer Gesellschaft, SatCom, Stefan Bund
</span>
</div>
</body></html>"""
SEARCH_PHP="""
<?php include 'search_functions.php'; ?>
<?php search(); ?>"""
SEARCH_PATHS_PHP="""<?php
function paths() {
return array(
"../${index}/",
}}
);
}
?>"""
header = yaptu.process(HEADER, globals(), env.Dictionary(),
TITLE = "Documentation and API reference")
footer = yaptu.process(FOOTER, globals(), env.Dictionary())
search_php = yaptu.process(HEADER + SEARCH_PHP.replace('<?','[[').replace('?>',']]') + FOOTER,
globals(), env.Dictionary(),
TITLE = "Search results")
search_paths_php = yaptu.process(SEARCH_PATHS_PHP, globals(), env.Dictionary())
env.Command('doxy-header.html', Value(header), writeTemplate)
env.Command('doxy-footer.html', Value(footer), writeTemplate)
env.Alias('all_docs',
env.Command('search.php', [ Value(search_php), 'html-munge.xsl' ],
[ writeTemplate,
'xsltproc --nonet --html --stringparam topdir .. -o - ${SOURCES[1]} $TARGET 2>/dev/null'
+ "| sed"
+ r" -e 's/\[\[/<?/g' -e 's/\]\]/?>/g'"
+ r" -e 's/\$$projectname/Overview/g'"
+ r" -e 's/\$$title/Search results/g'"
'mv ${TARGET}.tmp ${TARGET}' ] ))
env.Alias('all_docs',
env.Command('search_paths.php', Value(search_paths_php), writeTemplate))
env.Alias('install_all',
env.Install( '$DOCINSTALLDIR/doclib', [ 'favicon.ico',
'logo-head.png',
'search.php',
'search_functions.php',
'search_paths.php',
'senf.css' ] ))
env.Clean('all', 'doxy-header.html') # I should not need this but I do ...
env.Clean('all_docs', 'doxy-header.html') # I should not need this but I do ...