=== SCons ===

[#17867] Adds option to SCONS to generate Python API documentation

Added patch from Brandano with some small improvements (BF_DOCDIR, clean) by yours truly.

To use make sure you have epydoc installed. Enable with WITH_BF_BPYDOC=1.

diff --git a/SConstruct b/SConstruct
index e7d4a4e77bdbfa86c825e18a9a08c404877918c6..f15aa8bfa2241d65e442d44cf5be4b2b3a65c835 100644 (file)
--- a/SConstruct
+++ b/SConstruct
@@ -277,15 +277,15 @@ if 'blenderlite' in B.targets:
     env['WITH_BF_BINRELOC'] = False
     env['BF_BUILDINFO'] = False
     env['BF_NO_ELBEEM'] = True
-    
-
 
 # lastly we check for root_build_dir ( we should not do before, otherwise we might do wrong builddir
 #B.root_build_dir = B.arguments.get('BF_BUILDDIR', '..'+os.sep+'build'+os.sep+platform+os.sep)
 B.root_build_dir = env['BF_BUILDDIR']
-env['BUILDDIR'] = B.root_build_dir
+B.doc_build_dir = env['BF_DOCDIR']
 if not B.root_build_dir[-1]==os.sep:
     B.root_build_dir += os.sep
+if not B.doc_build_dir[-1]==os.sep:
+    B.doc_build_dir += os.sep
     
 # We do a shortcut for clean when no quicklist is given: just delete
 # builddir without reading in SConscripts
@@ -294,8 +294,18 @@ if 'clean' in B.targets:
     do_clean = True
 
 if not quickie and do_clean:
+    if os.path.exists(B.doc_build_dir):
+        print B.bc.HEADER+'Cleaning doc dir...'+B.bc.ENDC
+        dirs = os.listdir(B.doc_build_dir)
+        for entry in dirs:
+            if os.path.isdir(B.doc_build_dir + entry) == 1:
+                print "clean dir %s"%(B.doc_build_dir+entry)
+                shutil.rmtree(B.doc_build_dir+entry)
+            else: # remove file
+                print "remove file %s"%(B.doc_build_dir+entry)
+                os.remove(B.root_build_dir+entry)
     if os.path.exists(B.root_build_dir):
-        print B.bc.HEADER+'Cleaning...'+B.bc.ENDC
+        print B.bc.HEADER+'Cleaning build dir...'+B.bc.ENDC
         dirs = os.listdir(B.root_build_dir)
         for entry in dirs:
             if os.path.isdir(B.root_build_dir + entry) == 1:
@@ -321,6 +331,8 @@ if not os.path.isdir ( B.root_build_dir):
     os.makedirs ( B.root_build_dir + 'extern' )
     os.makedirs ( B.root_build_dir + 'lib' )
     os.makedirs ( B.root_build_dir + 'bin' )
+if not os.path.isdir(B.doc_build_dir):
+    os.makedirs ( B.doc_build_dir )
 
 Help(opts.GenerateHelpText(env))
 
@@ -565,5 +577,6 @@ if not env['WITHOUT_BF_INSTALL']:
 # TODO: build stubs and link into blenderplayer
 
 #------------ EPYDOC
-# TODO: run epydoc
+if env['WITH_BF_BPYDOC']:
+    SConscript(['source/blender/python/api2_2x/doc/SConscript'])
 

diff --git a/config/darwin-config.py b/config/darwin-config.py
index 0eb275dcaf4c9efe0718b19241795d00795090e6..cc6c6ef76aff736bd0fba5e629838884add3d14f 100644 (file)
--- a/config/darwin-config.py
+++ b/config/darwin-config.py
@@ -268,3 +268,4 @@ BF_DEBUG_FLAGS = '-g'
 
 BF_BUILDDIR='../build/darwin'
 BF_INSTALLDIR='../install/darwin'
+BF_DOCDIR='../install/doc'

diff --git a/config/linux2-config.py b/config/linux2-config.py
index 2b7bf074f83eb14a29a6e26207bc814886a4e1f5..74853de70b65718ae784f3c462005179523ec342 100644 (file)
--- a/config/linux2-config.py
+++ b/config/linux2-config.py
@@ -205,6 +205,7 @@ BF_DEBUG_FLAGS = '-g'
 
 BF_BUILDDIR = '../build/linux2'
 BF_INSTALLDIR='../install/linux2'
+BF_DOCDIR='../install/doc'
 
 
 #Link against pthread

diff --git a/config/linuxcross-config.py b/config/linuxcross-config.py
index 9d58512151b6ff0e9c222cb51bf6b13c943b5f5b..13f477d21f3eb43aa8948e76d16a07471f910827 100644 (file)
--- a/config/linuxcross-config.py
+++ b/config/linuxcross-config.py
@@ -148,3 +148,4 @@ BF_DEBUG_FLAGS= ''
 
 BF_BUILDDIR = '../build/linuxcross'
 BF_INSTALLDIR='../install/linuxcross'
+BF_DOCDIR='../install/doc'

diff --git a/config/openbsd3-config.py b/config/openbsd3-config.py
index 5ef3d90f168afcfbde0be7115a0cfb3f983d9869..1cd93008561e69d3987af45be0ad1f2c6e3aff22 100644 (file)
--- a/config/openbsd3-config.py
+++ b/config/openbsd3-config.py
@@ -163,3 +163,4 @@ BF_DEBUG_FLAGS = '-g'
 
 BF_BUILDDIR='../build/openbsd3'
 BF_INSTALLDIR='../install/openbsd3'
+BF_DOCDIR='../install/doc'

diff --git a/config/sunos5-config.py b/config/sunos5-config.py
index bfb1513ca3f545066a25ba15722ffb8cd4c59530..a5ba33e44cd7a7608e8adf4c57c4a902fad56862 100644 (file)
--- a/config/sunos5-config.py
+++ b/config/sunos5-config.py
@@ -177,6 +177,7 @@ BF_DEBUG_FLAGS = ''
 
 BF_BUILDDIR = '../build/sunos5'
 BF_INSTALLDIR='../install/sunos5'
+BF_DOCDIR='../install/doc'
 
 
 PLATFORM_LINKFLAGS = ['']

diff --git a/config/win32-mingw-config.py b/config/win32-mingw-config.py
index 4ff93bf7078a294e8f4cb215dc0e16b2bf4f0542..65b7beb79adb7d27d831b4f718a577e6f5167b92 100644 (file)
--- a/config/win32-mingw-config.py
+++ b/config/win32-mingw-config.py
@@ -167,3 +167,4 @@ BF_PROFILE = 'false'
 
 BF_BUILDDIR = '..\\build\\win32-mingw'
 BF_INSTALLDIR='..\\install\\win32-mingw'
+BF_DOCDIR = '..\\install\\doc'
\ No newline at end of file

diff --git a/config/win32-vc-config.py b/config/win32-vc-config.py
index 1b7737ed004510376e6014d7ea4fc2f27124644a..14fd8b3aac75ba739c17e2333e267cb19a855167 100644 (file)
--- a/config/win32-vc-config.py
+++ b/config/win32-vc-config.py
@@ -187,3 +187,4 @@ PLATFORM_LINKFLAGS = '''
 
 BF_BUILDDIR = '..\\build\\win32-vc'
 BF_INSTALLDIR='..\\install\\win32-vc'
+BF_DOCDIR='..\\install\\doc'

diff --git a/source/blender/python/api2_2x/doc/SConscript b/source/blender/python/api2_2x/doc/SConscript
new file mode 100644 (file)
index 0000000..49d2089
--- /dev/null
+++ b/source/blender/python/api2_2x/doc/SConscript
@@ -0,0 +1,28 @@
+#!/usr/bin/python
+Import ('env')
+
+
+from optparse import OptionParser
+try:
+    import epydoc
+except ImportError:
+    print "No epydoc install detected, Python API Docs will not be generated "
+if epydoc:
+    from epydoc.docbuilder import build_doc_index
+    from epydoc import cli
+    names = env.Glob("source/blender/python/api2_2x/doc/[A-Z]*.py")
+    docindex = build_doc_index(names)
+    optvalues = cli.OPTION_DEFAULTS
+    optvalues["verbose"] = 1
+    optvalues["target"] = env["BF_DOCDIR"]+"/BPY_API/"
+    optvalues["url"] = "http://www.blender.org"
+    optvalues["top"] = "API_intro"
+    optvalues["name"] = "Blender"
+    optvalues["noprivate"] = 1
+    optvalues["noframes"] = 1
+    optvalues["names"] = names
+    optparser = OptionParser()
+    optparser.set_defaults(**optvalues)
+    (options, args) = optparser.parse_args()
+    cli.write_html(docindex, options)
+

diff --git a/tools/Blender.py b/tools/Blender.py
index 330a371381721cedcb6a366705c28b16b27bad03..9baeb374af893ad619868e4d65a058763ccd99fe 100644 (file)
--- a/tools/Blender.py
+++ b/tools/Blender.py
@@ -35,6 +35,7 @@ GetBuildPath = SConsEnvironment.GetBuildPath
 
 # a few globals
 root_build_dir = ''
+doc_build_dir = ''
 quickie = None # Anything else than None if BF_QUICK has been passed
 quicklist = [] # The list of libraries/programs to compile during a quickie
 program_list = [] # A list holding Nodes to final binaries, used to create installs

diff --git a/tools/btools.py b/tools/btools.py
index 04ff9bcd9148fdf103bdbd91fc80b9b68d047af6..9db7d48cc9821f992df8b69f0517d3df66af62ae 100755 (executable)
--- a/tools/btools.py
+++ b/tools/btools.py
@@ -68,6 +68,7 @@ def validate_arguments(args, bc):
             'BF_FANCY', 'BF_QUIET',
             'BF_X264_CONFIG',
             'BF_XVIDCORE_CONFIG',
+            'WITH_BF_BPYDOC',
             ]
 
     arg_list = ['BF_DEBUG', 'BF_QUIET', 'BF_CROSS', 'BF_UPDATE',
@@ -75,7 +76,8 @@ def validate_arguments(args, bc):
             'BF_BUILDDIR', 'BF_FANCY', 'BF_QUICK', 'BF_PROFILE',
             'BF_DEBUG_FLAGS', 'BF_BSC', 'BF_CONFIG',
             'BF_PRIORITYLIST', 'BF_BUILDINFO','CC', 'CXX', 'BF_QUICKDEBUG',
-            'BF_LISTDEBUG', 'LCGDIR', 'BF_X264_CONFIG', 'BF_XVIDCORE_CONFIG']
+            'BF_LISTDEBUG', 'LCGDIR', 'BF_X264_CONFIG', 'BF_XVIDCORE_CONFIG',
+            'BF_DOCDIR']
 
     all_list = opts_list + arg_list
     okdict = {}
@@ -335,6 +337,7 @@ def read_opts(cfg, args):
 
         ('BF_BUILDDIR', 'Build dir', ''),
         ('BF_INSTALLDIR', 'Installation dir', ''),
+        ('BF_DOCDIR', 'Dir where BPy documentation will be created', ''),
 
         ('CC', 'C compiler to use', ''),
         ('CXX', 'C++ compiler to use', ''),
@@ -350,6 +353,7 @@ def read_opts(cfg, args):
 
         ('BF_X264_CONFIG', 'configuration flags for x264', ''),
         ('BF_XVIDCORE_CONFIG', 'configuration flags for xvidcore', ''),
+        (BoolOption('WITH_BF_BPYDOC', 'Generate BPY API documentation', 'false')),
         
         ('BF_CONFIG', 'SCons python config file used to set default options', 'user_config.py'),