sphinx doc generation

- include default values as well as min/max.
- partial rebuilds, so we dont have to build all docs each time, only the changed files.

3 files changed, 63 insertions, 17 deletions

diff --git a/release/scripts/modules/rna_info.py b/release/scripts/modules/rna_info.py
index d0a9de329c1..7a1f5d1bc4a 100644
--- a/release/scripts/modules/rna_info.py
+++ b/release/scripts/modules/rna_info.py
@@ -245,11 +245,18 @@ class InfoPropertyRNA:
             type_str += self.type
             if self.array_length:
                 type_str += " array of %d items" % (self.array_length)
-
+                
             if self.type in ("float", "int"):
                 type_str += " in [%s, %s]" % (range_str(self.min), range_str(self.max))
             elif self.type == "enum":
                 type_str += " in [%s]" % ', '.join([("'%s'" % s) for s in self.enum_items])
+
+            if not (as_arg or as_ret):
+                # write default property, ignore function args for this
+                default_str = self.get_default_string()
+                if default_str:
+                    type_str += ", default %s" % default_str
+
         else:
             if self.type == "collection":
                 if self.collection_type:
@@ -261,17 +268,22 @@ class InfoPropertyRNA:
 
             type_str += collection_str + (class_fmt % self.fixed_type.identifier)
 
+        # setup qualifiers for this value.
+        type_info = []
         if as_ret:
             pass
         elif as_arg:
             if not self.is_required:
-                type_str += ", (optional)"
+                type_info.append("optional")
         else: # readonly is only useful for selfs, not args
             if self.is_readonly:
-                type_str += ", (readonly)"
+                type_info.append("readonly")
 
         if self.is_never_none:
-            type_str += ", (never None)"
+            type_info.append("never None")
+
+        if type_info:
+            type_str += (", (%s)" % ", ".join(type_info))
 
         return type_str
 
diff --git a/source/blender/python/doc/sphinx_doc_gen.py b/source/blender/python/doc/sphinx_doc_gen.py
index 67cd462b3c1..96e31e01f8e 100644
--- a/source/blender/python/doc/sphinx_doc_gen.py
+++ b/source/blender/python/doc/sphinx_doc_gen.py
@@ -51,6 +51,7 @@ EXAMPLE_SET = set()
 EXAMPLE_SET_USED = set()
 
 _BPY_STRUCT_FAKE = "bpy_struct"
+_BPY_FULL_REBUILD = False
 
 def range_str(val):
     if val < -10000000:	return '-inf'
@@ -663,22 +664,56 @@ if __name__ == '__main__':
         import shutil
 
         path_in = 'source/blender/python/doc/sphinx-in'
-        path_out = 'source/blender/python/doc/sphinx-in'
+        path_out = 'source/blender/python/doc/sphinx-out'
         path_examples = 'source/blender/python/doc/examples'
+        # only for partial updates
+        path_in_tmp = path_in + "-tmp"
 
-        shutil.rmtree(path_in, True)
-        shutil.rmtree(path_out, True)
-        
         for f in os.listdir(path_examples):
             if f.endswith(".py"):
                 EXAMPLE_SET.add(os.path.splitext(f)[0])
-        
-        rna2sphinx(path_in)
 
-        # for fast module testing
-        # os.system("rm source/blender/python/doc/sphinx-in/bpy.types.*.rst")
-        # os.system("rm source/blender/python/doc/sphinx-in/bpy.ops.*.rst")
-        
+
+        # only for full updates
+        if _BPY_FULL_REBUILD:
+            shutil.rmtree(path_in, True)
+            shutil.rmtree(path_out, True)
+        else:
+            # write here, then move
+            shutil.rmtree(path_in_tmp, True)
+
+        rna2sphinx(path_in_tmp)
+
+        if not _BPY_FULL_REBUILD:
+            import filecmp
+
+            # now move changed files from 'path_in_tmp' --> 'path_in'
+            file_list_path_in = set(os.listdir(path_in))
+            file_list_path_in_tmp = set(os.listdir(path_in_tmp))
+            
+            # remove deprecated files that have been removed.
+            for f in sorted(file_list_path_in):
+                if f not in file_list_path_in_tmp:
+                    print("\tdeprecated: %s" % f)
+                    os.remove(os.path.join(path_in, f))
+
+            # freshen with new files.
+            for f in sorted(file_list_path_in_tmp):
+                f_from = os.path.join(path_in_tmp, f)
+                f_to = os.path.join(path_in, f)
+
+                do_copy = True
+                if f in file_list_path_in:
+                    if filecmp.cmp(f_from, f_to):
+                        do_copy = False
+                
+                if do_copy:
+                    print("\tupdating: %s" % f)
+                    shutil.copy(f_from, f_to)
+                '''else:
+                    print("\tkeeping: %s" % f) # eh, not that useful'''
+
+
         EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED
         if EXAMPLE_SET_UNUSED:
             print("\nUnused examples found in '%s'..." % path_examples)
diff --git a/source/blender/python/doc/sphinx_doc_gen.sh b/source/blender/python/doc/sphinx_doc_gen.sh
index 3f5460a0626..03fe9a2efec 100755
--- a/source/blender/python/doc/sphinx_doc_gen.sh
+++ b/source/blender/python/doc/sphinx_doc_gen.sh
@@ -1,14 +1,13 @@
 #!/bin/sh
 # run from the blender source dir
 #   bash source/blender/python/doc/sphinx_doc_gen.sh
-# ssh upload means you need a login into the server
+# ssh upload means you need an account on the server
 
 BLENDER="./blender.bin"
 SSH_HOST="ideasman42@emo.blender.org"
 SSH_UPLOAD="/data/www/vhosts/www.blender.org/documentation/250PythonDoc"
 
-# clear doc dir
-rm -rf ./source/blender/python/doc/sphinx-in ./source/blender/python/doc/sphinx-out
+# dont delete existing docs, now partial updates are used for quick builds.
 $BLENDER -b -P ./source/blender/python/doc/sphinx_doc_gen.py
 
 # html