X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=senfscons%2FSENFSCons.py;fp=senfscons%2FSENFSCons.py;h=b6862e5b6c20ecaff5d5550822e412ef6654bab3;hb=7746a408cc69f62722ce87c35dab1cabe03d7626;hp=58a9841460aedeb676a6f16a8028db6a2e1865e0;hpb=ce4eb240599560a7c69222c22d8916ab6ebe450c;p=senf.git diff --git a/senfscons/SENFSCons.py b/senfscons/SENFSCons.py index 58a9841..b6862e5 100644 --- a/senfscons/SENFSCons.py +++ b/senfscons/SENFSCons.py @@ -439,195 +439,66 @@ def InstallIncludeFiles(env, files): ## \brief Build documentation with doxygen # -# The doxygen target helper will build software documentation using -# the given \a doxyfile (which defaults to \c Doxyfile). The Doxygen -# builder used supports automatic dependency generation (dependencies -# are automatically generated from the parameters specified in the \a -# doxyfile), automatic target emitters (the exact targets created are -# found parsing the \a doxyfile) and lots of other features. See the -# Doxygen builder documentation -# -# If \a extra_sources are given, the generated documentation will -# depend on them. This can be used to build images or other -# supplementary files. -# -# The doxygen target helper extends the builder with additional -# functionality: -# -# \li Fix tagfiles by removing namespace entries. These entries only -# work for namespaces completely defined in a single module. As -# soon as another module (which references the tagfile) has it's -# own members in that namespace, the crosslinking will break. -# \li If \c DOXY_HTML_XSL is defined as a construction environment -# variable, preprocess all generated html files (if html files are -# generated) by the given XSLT stylesheet. Since the HTML -# generated by doxygen is broken, we first filter the code through -# HTML-\c tidy and filter out some error messages. -# \li If xml output is generated we create files \c bug.xmli and \c -# todo.xmli which contain all bugs and todo items specified in the -# sources. The format of these files is much more suited to -# postprocessing and is a more database like format as the doxygen -# generated files (which are more presentation oriented). if \c -# DOXY_XREF_TYPES is given, it will specify the cross reference -# types to support (defaults to \c bug and \c todo). See \xrefitem -# in the doxygen documentation. -# # \ingroup target def Doxygen(env, doxyfile = "Doxyfile", extra_sources = []): - if not 'all' in BUILD_TARGETS and not 'doc' in BUILD_TARGETS and not 'all_docs' in BUILD_TARGETS: - return [] - # ARGHHH !!! without the [:] we are changing the target list - # ||| WITHIN THE DOXYGEN BUILDER - docs = env.Doxygen(doxyfile)[:] - xmlnode = None - htmlnode = None - tagnode = None - for doc in docs: - if isinstance(doc,SCons.Node.FS.Dir): continue - if doc.name == 'xml.stamp' : xmlnode = doc - if doc.name == 'html.stamp' : htmlnode = doc - if doc.name == 'search.idx' : continue - if os.path.splitext(doc.name)[1] == '.stamp' : continue # ignore other file stamps - # otherwise it must be the tag file - tagnode = doc - - if tagnode: - # Postprocess the tag file to remove the (broken) namespace - # references - env.AddPostAction( - docs, - SCons.Action.Action("xsltproc --nonet -o %(target)s.temp %(template)s %(target)s && mv %(target)s.temp %(target)s" - % { 'target': tagnode.abspath, - 'template': os.path.join(basedir,"tagmunge.xsl") })) - - if htmlnode and env.get('DOXY_HTML_XSL'): - xslfile = env.File(env['DOXY_HTML_XSL']) - reltopdir = '../' * len(htmlnode.dir.abspath[len(env.Dir('#').abspath)+1:].split('/')) - if reltopdir : reltopdir = reltopdir[:-1] - else : reltopdir = '.' - env.AddPostAction( - docs, - SCons.Action.Action(("for html in %s/*.html; do " + - " echo $$html;" + - " mv $${html} $${html}.orig;" + - " sed -e 's/id=\"current\"/class=\"current\"/' $${html}.orig" + - " | tidy -ascii -q --wrap 0 --show-warnings no --fix-uri no " + - " | sed -e 's/name=\"\([^\"]*\)\"\([^>]*\) id=\"\\1\"/name=\"\\1\"\\2/g'" + - " | xsltproc --novalid --nonet --html --stringparam topdir %s -o $${html} %s -;" - "done; true") - % (htmlnode.dir.abspath, reltopdir, xslfile.abspath))) - for doc in docs: - env.Depends(doc, xslfile) - - if xmlnode: - xrefs = [] - for type in env.get("DOXY_XREF_TYPES",[ "bug", "todo" ]): - xref = os.path.join(xmlnode.dir.abspath,type+".xml") - xref_pp = env.Command(xref+'i', [ xref, os.path.join(basedir,'xrefxtract.xslt'), xmlnode ], - [ "test -s $SOURCE && xsltproc --nonet -o $TARGET" + - " --stringparam module $MODULE" + - " --stringparam type $TYPE" + - " ${SOURCES[1]} $SOURCE || touch $TARGET" ], - MODULE = xmlnode.dir.dir.dir.abspath[ - len(env.Dir('#').abspath)+1:], - TYPE = type) - env.SideEffect(xref, xmlnode) - env.AddPreAction(docs, "rm -f %s" % (xref,)) - env.AddPostAction(docs, "test -r %s || touch %s" % (xref,xref)) - xrefs.extend(xref_pp) - docs.extend(xrefs) - - if extra_sources and htmlnode: - env.Depends(docs, - [ env.CopyToDir( source=source, target=htmlnode.dir ) - for source in extra_sources ]) - - if extra_sources and xmlnode: - env.Depends(docs, - [ env.CopyToDir( source=source, target=xmlnode.dir ) - for source in extra_sources ]) - - if not htmlnode and not xmlnode: - env.Depends(docs, extra_sources) - - for doc in docs : - env.Alias('all_docs', doc) - env.Clean('all_docs', doc) - env.Clean('all', doc) - + # There is one small problem we need to solve with this builder: The Doxygen builder reads + # the Doxyfile and thus depends on the environment variables set by doclib/doxygen.sh. We + # thus have to provide all necessary definitions here manually via DOXYENV ! + + if type(doxyfile) is type(""): + doxyfile = env.File(doxyfile) + + # Module name is derived from the doxyfile path + # Utils/Console/Doxyfile -> Utils_Console + module = doxyfile.dir.abspath[len(env.Dir('#').abspath)+1:].replace('/','_') + if not module : module = "Main" + + # Rule to generate tagfile + # (need to exclude the 'clean' case, otherwise we'll have duplicate nodes) + if not env.GetOption('clean'): + env.Append(ALL_TAGFILES = + env.Doxygen(doxyfile, + DOXYOPTS = [ '--tagfile-name', '"${MODULE}.tag"', + '--tagfile' ], + DOXYENV = { 'TOPDIR' : env.Dir('#').abspath, + 'output_dir' : 'doc', + 'html_dir' : 'html', + 'html' : 'NO', + 'generate_tagfile': 'doc/${MODULE}.tag' }, + MODULE = module )[0].abspath) + + # Rule to generate HTML documentation + doc = env.Doxygen(doxyfile, + DOXYOPTS = [ '--tagfiles', '"$ALL_TAGFILES"', + '--tagfile-name', '"${MODULE}.tag"', + '--html' ], + MODULE = module, + DOXYENV = { 'TOPDIR' : env.Dir('#').abspath, + 'tagfiles' : '${ALL_TAGFILES}', + 'output_dir' : 'doc', + 'html_dir' : 'html', + 'html' : 'YES' } ) + + # Copy the extra_sources (the images) into the documentation directory + # (need to exclude the 'clean' case otherwise there are multiple ways to clean the copies) + if not env.GetOption('clean'): + if extra_sources: + env.Depends(doc, + [ env.CopyToDir( source=source, target=doc[0].dir ) + for source in extra_sources ]) + + # Install documentation into DOCINSTALLDIR l = len(env.Dir('#').abspath) - if htmlnode: - env.Alias('install_all', - env.Command('$DOCINSTALLDIR' + htmlnode.dir.abspath[l:], htmlnode.dir, - [ SCons.Defaults.Copy('$TARGET','$SOURCE') ])) - if tagnode: - env.Alias('install_all', - env.Install( '$DOCINSTALLDIR' + tagnode.dir.abspath[l:], - tagnode )) + env.Alias('install_all', + env.Command('$DOCINSTALLDIR' + doc[0].dir.abspath[l:], doc[0].dir, + [ SCons.Defaults.Copy('$TARGET','$SOURCE') ])) - return docs - -## \brief Build combined doxygen cross-reference -# -# This command will build a complete cross-reference of \c xrefitems -# accross all modules. -# -# Right now, this command is very project specific. It needs to be -# generalized. -# -# \ingroup target -def DoxyXRef(env, docs=None, - HTML_HEADER = None, HTML_FOOTER = None, - TITLE = "Cross-reference of action points"): - if docs is None: - docs = env.Alias('all_docs')[0].sources - xrefs = [ doc for doc in docs if os.path.splitext(doc.name)[1] == ".xmli" ] - xref = env.Command("doc/html/xref.xml", xrefs, - [ "echo '' > $TARGET", - "echo '' >> $TARGET", - "cat $SOURCES >> $TARGET", - "echo '' >>$TARGET" ]) - - # Lastly we create the html file - sources = [ xref, "%s/xrefhtml.xslt" % basedir ] - if HTML_HEADER : sources.append(HTML_HEADER) - if HTML_FOOTER : sources.append(HTML_FOOTER) - - commands = [] - if HTML_HEADER: - commands.append("sed" + - " -e 's/\\$$title/$TITLE/g'" + - " -e 's/\\$$projectname/Overview/g'" + - " ${SOURCES[2]} > $TARGET") - commands.append("xsltproc" + - " --stringparam title '$TITLE'" + - " --stringparam types '$DOXY_XREF_TYPES'" + - " ${SOURCES[1]} $SOURCE >> $TARGET") - if HTML_FOOTER: - commands.append( - "sed -e 's/\\$$title/$TITLE/g' -e 's/\\$$projectname/Overview/g' ${SOURCES[%d]} >> $TARGET" - % (HTML_HEADER and 3 or 2)) - - if env.get('DOXY_HTML_XSL'): - xslfile = env.File(env['DOXY_HTML_XSL']) - reltopdir = '../' * len(xref[0].dir.abspath[len(env.Dir('#').abspath)+1:].split('/')) - if reltopdir : reltopdir = reltopdir[:-1] - else : reltopdir = '.' - commands.append(("xsltproc -o ${TARGET}.tmp" + - " --nonet --html" + - " --stringparam topdir %s" + - " ${SOURCES[-1]} $TARGET 2>/dev/null") - % reltopdir) - commands.append("mv ${TARGET}.tmp ${TARGET}") - sources.append(xslfile) - - xref = env.Command("doc/html/xref.html", sources, commands, - TITLE = TITLE) - - env.Alias('all_docs',xref) - return xref + # Useful aliases + env.Alias('all_docs', doc) + env.Clean('all_docs', doc) + env.Clean('all', doc) + return doc ## \brief Build library #