From ba4425ab5227fd9597fccd368bffff6bf1032149 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 10 Sep 2011 11:25:53 +0200 Subject: Imported Upstream version 2.1.0 --- doc/SConscript | 145 ++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 108 insertions(+), 37 deletions(-) (limited to 'doc/SConscript') diff --git a/doc/SConscript b/doc/SConscript index e0b3f71..54b620e 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -3,7 +3,7 @@ # # -# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation +# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -43,7 +43,7 @@ dist_doc_tar_gz = '$DISTDIR/scons-doc-${VERSION}.tar.gz' # if lynx is available to do the dump. # fig2dev = whereis('fig2dev') -epydoc = whereis('epydoc') +epydoc_cli = whereis('epydoc') groff = whereis('groff') lynx = whereis('lynx') man2html = whereis('man2html') @@ -121,7 +121,7 @@ scons_doc_files = list(map(chop, open(manifest_xml_in).readlines())) scons_doc_files = [File('#src/engine/'+x).rstr() for x in scons_doc_files] if not jw: - print "jw not found, skipping building User Guide." + print "doc: jw not found, skipping building User Guide." else: # # Always create a version.xml file containing the version information @@ -151,6 +151,8 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. builders_gen = os.path.join(build, 'user', 'builders.gen') builders_mod = os.path.join(build, 'user', 'builders.mod') + functions_gen = os.path.join(build, 'user', 'functions.gen') + functions_mod = os.path.join(build, 'user', 'functions.mod') tools_gen = os.path.join(build, 'user', 'tools.gen') tools_mod = os.path.join(build, 'user', 'tools.mod') variables_gen = os.path.join(build, 'user', 'variables.gen') @@ -163,11 +165,12 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. # vs. the other. The *.gen and *.mod targets will still be dependent # on the list of the files themselves. doc_output_files = [builders_gen, builders_mod, + functions_gen, functions_mod, tools_gen, tools_mod, variables_gen, variables_mod] b = env.Command(doc_output_files, scons_doc_files, - "$PYTHON $SCONS_PROC_PY --xml -b ${TARGETS[0]},${TARGETS[1]} -t ${TARGETS[2]},${TARGETS[3]} -v ${TARGETS[4]},${TARGETS[5]} $( $SOURCES $)") + "$PYTHON $SCONS_PROC_PY --xml -b ${TARGETS[0]},${TARGETS[1]} -f ${TARGETS[2]},${TARGETS[3]} -t ${TARGETS[4]},${TARGETS[5]} -v ${TARGETS[6]},${TARGETS[7]} $( $SOURCES $)") env.Depends(b, "$SCONS_PROC_PY") env.Local(b) @@ -403,11 +406,11 @@ for m in man_page_list: x = orig_env.SCons_revision(os.path.join(build, 'man', m), os.path.join('man', m)) -man_i_files = ['builders.man', 'tools.man', 'variables.man'] +man_i_files = ['builders.man', 'functions.man', 'tools.man', 'variables.man'] man_intermediate_files = [os.path.join(build, 'man', x) for x in man_i_files] -cmd = "$PYTHON $SCONS_PROC_PY --man -b ${TARGETS[0]} -t ${TARGETS[1]} -v ${TARGETS[2]} $( $SOURCES $)" +cmd = "$PYTHON $SCONS_PROC_PY --man -b ${TARGETS[0]} -f ${TARGETS[1]} -t ${TARGETS[2]} -v ${TARGETS[3]} $( $SOURCES $)" man_intermediate_files = env.Command(man_intermediate_files, scons_doc_files, cmd) @@ -458,8 +461,79 @@ for man_1 in man_page_list: tar_deps.append(html) tar_list.append(html) -if not epydoc: - print "epydoc not found, skipping building API documentation." +if not epydoc_cli: + try: + import epydoc + except ImportError: + epydoc = None + else: + # adding Epydoc builder using imported module + def epydoc_builder_action(target, source, env): + """ + Take a list of `source` files and build docs for them in + `target` dir. + + `target` and `source` are lists. + + Uses OUTDIR and EPYDOCFLAGS environment variables. + + http://www.scons.org/doc/2.0.1/HTML/scons-user/x3594.html + """ + + # the epydoc build process is the following: + # 1. build documentation index + # 2. feed doc index to writer for docs + + from epydoc.docbuilder import build_doc_index + from epydoc.docwriter.html import HTMLWriter + from epydoc.docwriter.latex import LatexWriter + + # first arg is a list where can be names of python package dirs, + # python files, object names or objects itself + docindex = build_doc_index([str(src) for src in source]) + if docindex == None: + return -1 + + if env['EPYDOCFLAGS'] == '--html': + html_writer = HTMLWriter(docindex, + docformat='restructuredText', + prj_name='SCons', + prj_url='http://www.scons.org/') + try: + html_writer.write(env['OUTDIR']) + except OSError: # If directory cannot be created or any file cannot + # be created or written to. + return -2 + + """ + # PDF support requires external Linux utilites, so it's not crossplatform. + # Leaving for now. + # http://epydoc.svn.sourceforge.net/viewvc/epydoc/trunk/epydoc/src/epydoc/cli.py + + elif env['EPYDOCFLAGS'] == '--pdf': + pdf_writer = LatexWriter(docindex, + docformat='restructuredText', + prj_name='SCons', + prj_url='http://www.scons.org/') + """ + return 0 + + epydoc_commands = [ + Delete('$OUTDIR'), + epydoc_builder_action, + Touch('$TARGET'), + ] + +else: # epydoc_cli is found + epydoc_commands = [ + Delete('$OUTDIR'), + '$EPYDOC $EPYDOCFLAGS --debug --output $OUTDIR --docformat=restructuredText --name SCons --url http://www.scons.org/ $SOURCES', + Touch('$TARGET'), + ] + + +if not epydoc_cli and not epydoc: + print "doc: epydoc not found, skipping building API documentation." else: # XXX Should be in common with reading the same thing in # the SConstruct file. @@ -475,40 +549,37 @@ else: e = os.path.join(build, '..', 'scons', 'engine') sources = [os.path.join(e, x) for x in sources] - epydoc_commands = [ - Delete('$OUTDIR'), - '$EPYDOC $EPYDOCFLAGS --debug --output $OUTDIR --docformat=restructuredText --name SCons --url http://www.scons.org/ $SOURCES', - Touch('$TARGET'), - ] - htmldir = os.path.join(build, 'HTML', 'scons-api') env.Command('${OUTDIR}/index.html', sources, epydoc_commands, - EPYDOC=epydoc, EPYDOCFLAGS='--html', OUTDIR=htmldir) + EPYDOC=epydoc_cli, EPYDOCFLAGS='--html', OUTDIR=htmldir) tar_deps.append(htmldir) tar_list.append(htmldir) - # PDF and PostScript and TeX are built from the - # same invocation. - api_dir = os.path.join(build, 'scons-api') - api_pdf = os.path.join(api_dir, 'api.pdf') - api_ps = os.path.join(api_dir, 'api.ps') - api_tex = os.path.join(api_dir, 'api.tex') - api_targets = [api_pdf, api_ps, api_tex] - env.Command(api_targets, sources, epydoc_commands, - EPYDOC=epydoc, EPYDOCFLAGS='--pdf', OUTDIR=api_dir) - Local(api_targets) - - pdf_install = os.path.join(build, 'PDF', 'scons-api.pdf') - env.InstallAs(pdf_install, api_pdf) - tar_deps.append(pdf_install) - tar_list.append(pdf_install) - Local(pdf_install) - - ps_install = os.path.join(build, 'PS', 'scons-api.ps') - env.InstallAs(ps_install, api_ps) - tar_deps.append(ps_install) - tar_list.append(ps_install) - Local(ps_install) + if not epydoc_cli: + print "doc: command line epydoc is not found, skipping PDF/PS/Tex output" + else: + # PDF and PostScript and TeX are built from the + # same invocation. + api_dir = os.path.join(build, 'scons-api') + api_pdf = os.path.join(api_dir, 'api.pdf') + api_ps = os.path.join(api_dir, 'api.ps') + api_tex = os.path.join(api_dir, 'api.tex') + api_targets = [api_pdf, api_ps, api_tex] + env.Command(api_targets, sources, epydoc_commands, + EPYDOC=epydoc_cli, EPYDOCFLAGS='--pdf', OUTDIR=api_dir) + Local(api_targets) + + pdf_install = os.path.join(build, 'PDF', 'scons-api.pdf') + env.InstallAs(pdf_install, api_pdf) + tar_deps.append(pdf_install) + tar_list.append(pdf_install) + Local(pdf_install) + + ps_install = os.path.join(build, 'PS', 'scons-api.ps') + env.InstallAs(ps_install, api_ps) + tar_deps.append(ps_install) + tar_list.append(ps_install) + Local(ps_install) # # Now actually create the tar file of the documentation, -- cgit v1.2.3