← Back to branch summary

~siretart/ubuntu/utopic/blender/libav10

« back to all changes in this revision

Viewing changes to doc/python_api/sphinx_doc_gen.py

  • Committer: Package Import Robot
  • Author(s): Kevin Roy
  • Date: 2011-10-21 14:21:47 UTC
  • mfrom: (14.2.10 sid)
  • Revision ID: package-import@ubuntu.com-20111021142147-2yjgibwwnmqibacp
Tags: 2.59-1
http://bugs.debian.org/641085
http://bugs.debian.org/636177
* New Upstream Release 2.59 (Closes: #641085)
* debian/control: libglew dependency changed
  - changed Depends libglew1.5-dev to libglew1.6-dev
   due to transition. (Closes: #636177)
* update manpages
* change depends yafray to new yafaray packages 
      (Thanks to Matteo F. Vescovi)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/python_api/sphinx_doc_gen.py
29
29
 
30
30
    ./blender.bin --background --python doc/python_api/sphinx_doc_gen.py
31
31
 
32
 
  This will generate python files in doc/python_api/sphinx-in/,
33
 
  assuming that ./blender.bin is or links to the blender executable
 
32
  This will generate python files in doc/python_api/sphinx-in/
 
33
  providing ./blender.bin is or links to the blender executable
34
34
 
35
35
- Generate html docs by running...
36
36
 
37
37
    cd doc/python_api
38
38
    sphinx-build sphinx-in sphinx-out
39
39
 
40
 
  assuming that you have sphinx 1.0.7 installed
 
40
  This requires sphinx 1.0.7 to be installed.
41
41
 
42
42
For PDF generation
43
43
------------------
48
48
    make
49
49
'''
50
50
 
 
51
# Check we're running in blender
 
52
if __import__("sys").modules.get("bpy") is None:
 
53
    print("\nError, this script must run from inside blender2.5")
 
54
    print(script_help_msg)
 
55
 
 
56
    import sys
 
57
    sys.exit()
 
58
 
 
59
 
51
60
# Switch for quick testing
52
61
if 1:
53
62
    # full build
58
67
else:
59
68
    # for testing so doc-builds dont take so long.
60
69
    EXCLUDE_MODULES = (
61
 
        # "bpy.context",
 
70
        "bpy.context",
62
71
        "bpy.app",
63
72
        "bpy.path",
64
73
        "bpy.data",
67
76
        "bpy.context",
68
77
        "bpy.types",  # supports filtering
69
78
        "bpy.ops",  # supports filtering
70
 
        #"bpy_extras",
71
 
        "bge",
 
79
        "bpy_extras",
 
80
        # "bge",
72
81
        "aud",
73
82
        "bgl",
74
83
        "blf",
407
416
    del key, descr
408
417
 
409
418
    classes = []
 
419
    submodules = []
410
420
 
411
421
    for attribute in module_dir:
412
422
        if not attribute.startswith("_"):
428
438
                py_c_func2sphinx("", fw, module_name, None, attribute, value, is_class=False)
429
439
            elif value_type == type:
430
440
                classes.append((attribute, value))
 
441
            elif issubclass(value_type, types.ModuleType):
 
442
                submodules.append((attribute, value))
431
443
            elif value_type in (bool, int, float, str, tuple):
432
444
                # constant, not much fun we can do here except to list it.
433
445
                # TODO, figure out some way to document these!
435
447
                write_indented_lines("   ", fw, "constant value %s" % repr(value), False)
436
448
                fw("\n")
437
449
            else:
438
 
                print("\tnot documenting %s.%s" % (module_name, attribute))
 
450
                print("\tnot documenting %s.%s of %r type" % (module_name, attribute, value_type.__name__))
439
451
                continue
440
452
 
441
453
            attribute_set.add(attribute)
442
454
            # TODO, more types...
443
455
 
 
456
    # TODO, bpy_extras does this already, mathutils not.
 
457
    """
 
458
    if submodules:
 
459
        fw("\n"
 
460
           "**********\n"
 
461
           "Submodules\n"
 
462
           "**********\n"
 
463
           "\n"
 
464
           )
 
465
        for attribute, submod in submodules:
 
466
            fw("* :mod:`%s.%s`\n" % (module_name, attribute))
 
467
        fw("\n")
 
468
    """
 
469
 
444
470
    # write collected classes now
445
471
    for (type_name, value) in classes:
446
472
        # May need to be its own function
980
1006
    fw("\n")
981
1007
    fw("* `Quickstart Intro <http://wiki.blender.org/index.php/Dev:2.5/Py/API/Intro>`_ if you are new to scripting in blender and want to get you're feet wet!\n")
982
1008
    fw("* `Blender/Python Overview <http://wiki.blender.org/index.php/Dev:2.5/Py/API/Overview>`_ for a more complete explanation of python integration in blender\n")
 
1009
    fw("\n")
983
1010
 
984
1011
    fw("===================\n")
985
1012
    fw("Application Modules\n")
1019
1046
        fw("   mathutils.rst\n\n")
1020
1047
    if "mathutils.geometry" not in EXCLUDE_MODULES:
1021
1048
        fw("   mathutils.geometry.rst\n\n")
1022
 
    # XXX TODO
1023
 
    #fw("   bgl.rst\n\n")
 
1049
    if "bgl" not in EXCLUDE_MODULES:
 
1050
        fw("   bgl.rst\n\n")
1024
1051
    if "blf" not in EXCLUDE_MODULES:
1025
1052
        fw("   blf.rst\n\n")
1026
1053
    if "aud" not in EXCLUDE_MODULES:
1039
1066
        fw("   bge.types.rst\n\n")
1040
1067
        fw("   bge.logic.rst\n\n")
1041
1068
        fw("   bge.render.rst\n\n")
 
1069
        fw("   bge.texture.rst\n\n")
1042
1070
        fw("   bge.events.rst\n\n")
 
1071
        fw("   bge.constraints.rst\n\n")
1043
1072
 
1044
1073
    # rna generated change log
1045
1074
    fw("========\n")
1150
1179
        import mathutils.geometry as module
1151
1180
        pymodule2sphinx(BASEPATH, "mathutils.geometry", module, "Geometry Utilities")
1152
1181
 
1153
 
    if "mathutils.geometry" not in EXCLUDE_MODULES:
 
1182
    if "blf" not in EXCLUDE_MODULES:
1154
1183
        import blf as module
1155
1184
        pymodule2sphinx(BASEPATH, "blf", module, "Font Drawing")
1156
1185
 
1157
 
    # XXX TODO
1158
 
    #import bgl as module
1159
 
    #pymodule2sphinx(BASEPATH, "bgl", module, "Blender OpenGl wrapper")
1160
 
    #del module
 
1186
    if "bgl" not in EXCLUDE_MODULES:
 
1187
        #import bgl as module
 
1188
        #pymodule2sphinx(BASEPATH, "bgl", module, "Blender OpenGl wrapper")
 
1189
        #del module
 
1190
        import shutil
 
1191
        shutil.copy2(os.path.join(BASEPATH, "..", "rst", "bgl.rst"), BASEPATH)
1161
1192
 
1162
1193
    if "aud" not in EXCLUDE_MODULES:
1163
1194
        import aud as module
1171
1202
        shutil.copy2(os.path.join(BASEPATH, "..", "rst", "bge.types.rst"), BASEPATH)
1172
1203
        shutil.copy2(os.path.join(BASEPATH, "..", "rst", "bge.logic.rst"), BASEPATH)
1173
1204
        shutil.copy2(os.path.join(BASEPATH, "..", "rst", "bge.render.rst"), BASEPATH)
 
1205
        shutil.copy2(os.path.join(BASEPATH, "..", "rst", "bge.texture.rst"), BASEPATH)
1174
1206
        shutil.copy2(os.path.join(BASEPATH, "..", "rst", "bge.events.rst"), BASEPATH)
 
1207
        shutil.copy2(os.path.join(BASEPATH, "..", "rst", "bge.constraints.rst"), BASEPATH)
1175
1208
 
1176
1209
    shutil.copy2(os.path.join(BASEPATH, "..", "rst", "change_log.rst"), BASEPATH)
1177
1210
 
1196
1229
 
1197
1230
 
1198
1231
def main():
1199
 
    import bpy
1200
 
    if 'bpy' not in dir():
1201
 
        print("\nError, this script must run from inside blender2.5")
1202
 
        print(script_help_msg)
 
1232
    import shutil
 
1233
 
 
1234
    script_dir = os.path.dirname(__file__)
 
1235
    path_in = os.path.join(script_dir, "sphinx-in")
 
1236
    path_out = os.path.join(script_dir, "sphinx-out")
 
1237
    path_examples = os.path.join(script_dir, "examples")
 
1238
    # only for partial updates
 
1239
    path_in_tmp = path_in + "-tmp"
 
1240
 
 
1241
    if not os.path.exists(path_in):
 
1242
        os.mkdir(path_in)
 
1243
 
 
1244
    for f in os.listdir(path_examples):
 
1245
        if f.endswith(".py"):
 
1246
            EXAMPLE_SET.add(os.path.splitext(f)[0])
 
1247
 
 
1248
    # only for full updates
 
1249
    if _BPY_FULL_REBUILD:
 
1250
        shutil.rmtree(path_in, True)
 
1251
        shutil.rmtree(path_out, True)
1203
1252
    else:
1204
 
        import shutil
1205
 
 
1206
 
        script_dir = os.path.dirname(__file__)
1207
 
        path_in = os.path.join(script_dir, "sphinx-in")
1208
 
        path_out = os.path.join(script_dir, "sphinx-out")
1209
 
        path_examples = os.path.join(script_dir, "examples")
1210
 
        # only for partial updates
1211
 
        path_in_tmp = path_in + "-tmp"
1212
 
 
1213
 
        if not os.path.exists(path_in):
1214
 
            os.mkdir(path_in)
1215
 
 
1216
 
        for f in os.listdir(path_examples):
1217
 
            if f.endswith(".py"):
1218
 
                EXAMPLE_SET.add(os.path.splitext(f)[0])
1219
 
 
1220
 
        # only for full updates
1221
 
        if _BPY_FULL_REBUILD:
1222
 
            shutil.rmtree(path_in, True)
1223
 
            shutil.rmtree(path_out, True)
1224
 
        else:
1225
 
            # write here, then move
1226
 
            shutil.rmtree(path_in_tmp, True)
1227
 
 
1228
 
        rna2sphinx(path_in_tmp)
1229
 
 
1230
 
        if not _BPY_FULL_REBUILD:
1231
 
            import filecmp
1232
 
 
1233
 
            # now move changed files from 'path_in_tmp' --> 'path_in'
1234
 
            file_list_path_in = set(os.listdir(path_in))
1235
 
            file_list_path_in_tmp = set(os.listdir(path_in_tmp))
1236
 
 
1237
 
            # remove deprecated files that have been removed.
1238
 
            for f in sorted(file_list_path_in):
1239
 
                if f not in file_list_path_in_tmp:
1240
 
                    print("\tdeprecated: %s" % f)
1241
 
                    os.remove(os.path.join(path_in, f))
1242
 
 
1243
 
            # freshen with new files.
1244
 
            for f in sorted(file_list_path_in_tmp):
1245
 
                f_from = os.path.join(path_in_tmp, f)
1246
 
                f_to = os.path.join(path_in, f)
1247
 
 
1248
 
                do_copy = True
1249
 
                if f in file_list_path_in:
1250
 
                    if filecmp.cmp(f_from, f_to):
1251
 
                        do_copy = False
1252
 
 
1253
 
                if do_copy:
1254
 
                    print("\tupdating: %s" % f)
1255
 
                    shutil.copy(f_from, f_to)
1256
 
                '''else:
1257
 
                    print("\tkeeping: %s" % f) # eh, not that useful'''
1258
 
 
1259
 
        EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED
1260
 
        if EXAMPLE_SET_UNUSED:
1261
 
            print("\nUnused examples found in '%s'..." % path_examples)
1262
 
            for f in EXAMPLE_SET_UNUSED:
1263
 
                print("    %s.py" % f)
1264
 
            print("  %d total\n" % len(EXAMPLE_SET_UNUSED))
 
1253
        # write here, then move
 
1254
        shutil.rmtree(path_in_tmp, True)
 
1255
 
 
1256
    rna2sphinx(path_in_tmp)
 
1257
 
 
1258
    if not _BPY_FULL_REBUILD:
 
1259
        import filecmp
 
1260
 
 
1261
        # now move changed files from 'path_in_tmp' --> 'path_in'
 
1262
        file_list_path_in = set(os.listdir(path_in))
 
1263
        file_list_path_in_tmp = set(os.listdir(path_in_tmp))
 
1264
 
 
1265
        # remove deprecated files that have been removed.
 
1266
        for f in sorted(file_list_path_in):
 
1267
            if f not in file_list_path_in_tmp:
 
1268
                print("\tdeprecated: %s" % f)
 
1269
                os.remove(os.path.join(path_in, f))
 
1270
 
 
1271
        # freshen with new files.
 
1272
        for f in sorted(file_list_path_in_tmp):
 
1273
            f_from = os.path.join(path_in_tmp, f)
 
1274
            f_to = os.path.join(path_in, f)
 
1275
 
 
1276
            do_copy = True
 
1277
            if f in file_list_path_in:
 
1278
                if filecmp.cmp(f_from, f_to):
 
1279
                    do_copy = False
 
1280
 
 
1281
            if do_copy:
 
1282
                print("\tupdating: %s" % f)
 
1283
                shutil.copy(f_from, f_to)
 
1284
            '''else:
 
1285
                print("\tkeeping: %s" % f) # eh, not that useful'''
 
1286
 
 
1287
    EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED
 
1288
    if EXAMPLE_SET_UNUSED:
 
1289
        print("\nUnused examples found in '%s'..." % path_examples)
 
1290
        for f in EXAMPLE_SET_UNUSED:
 
1291
            print("    %s.py" % f)
 
1292
        print("  %d total\n" % len(EXAMPLE_SET_UNUSED))
1265
1293
 
1266
1294
    import sys
1267
1295
    sys.exit()