← Back to branch summary

~ubuntu-branches/ubuntu/trusty/blender/trusty

« back to all changes in this revision

Viewing changes to doc/python_api/sphinx_doc_gen.py

  • Committer: Package Import Robot
  • Author(s): Jeremy Bicha
  • Date: 2013-03-06 12:08:47 UTC
  • mfrom: (1.5.1) (14.1.8 experimental)
  • Revision ID: package-import@ubuntu.com-20130306120847-frjfaryb2zrotwcg
Tags: 2.66a-1ubuntu1
https://launchpad.net/bugs/1076930
https://launchpad.net/bugs/1089256
https://launchpad.net/bugs/1052743
https://launchpad.net/bugs/999024
* Resynchronize with Debian (LP: #1076930, #1089256, #1052743, #999024,
  #1122888, #1147084)
* debian/control:
  - Lower build-depends on libavcodec-dev since we're not
    doing the libav9 transition in Ubuntu yet

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/python_api/sphinx_doc_gen.py
35
35
    ./blender.bin --background --python doc/python_api/sphinx_doc_gen.py -- --output ../python_api
36
36
 
37
37
  For quick builds:
38
 
    ./blender.bin --background --python doc/python_api/sphinx_doc_gen.py -- --partial
 
38
    ./blender.bin --background --python doc/python_api/sphinx_doc_gen.py -- --partial bmesh.*
39
39
 
40
40
 
41
41
Sphinx: HTML generation
245
245
        "bgl",
246
246
        "blf",
247
247
        "bmesh",
 
248
        "bmesh.ops",
248
249
        "bmesh.types",
249
250
        "bmesh.utils",
250
251
        "bpy.app",
297
298
    __import__("aud")
298
299
except ImportError:
299
300
    BPY_LOGGER.debug("Warning: Built without 'aud' module, docs incomplete...")
300
 
    EXCLUDE_MODULES = EXCLUDE_MODULES + ("aud", )
 
301
    EXCLUDE_MODULES = list(EXCLUDE_MODULES) + ["aud"]
301
302
 
302
303
# examples
303
304
EXAMPLES_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "examples"))
315
316
INFO_DOCS = (
316
317
    ("info_quickstart.rst", "Blender/Python Quickstart: new to blender/scripting and want to get your feet wet?"),
317
318
    ("info_overview.rst", "Blender/Python API Overview: a more complete explanation of python integration"),
 
319
    ("info_tutorial_addon.rst", "Blender/Python Addon Tutorial: a step by step guide on how to write an addon from scratch"),
 
320
    ("info_api_reference.rst", "Blender/Python API Reference Usage: examples of how to use the API reference docs"),
318
321
    ("info_best_practice.rst", "Best Practice: Conventions to follow for writing good scripts"),
319
322
    ("info_tips_and_tricks.rst", "Tips and Tricks: Hints to help you while writing scripts for blender"),
320
323
    ("info_gotcha.rst", "Gotcha's: some of the problems you may come up against when writing scripts"),
399
402
 
400
403
available_themes = SPHINX_THEMES['bf'] + SPHINX_THEMES['sphinx']
401
404
if ARGS.sphinx_theme not in available_themes:
402
 
    print ("Please choose a theme among: %s" % ', '.join(available_themes))
 
405
    print("Please choose a theme among: %s" % ', '.join(available_themes))
403
406
    sys.exit()
404
407
 
405
408
if ARGS.sphinx_theme in SPHINX_THEMES['bf']:
609
612
    '''
610
613
    function or class method to sphinx
611
614
    '''
 
615
 
 
616
    if type(py_func) == type(bpy.types.Space.draw_handler_add):
 
617
        return
 
618
 
612
619
    arg_str = inspect.formatargspec(*inspect.getargspec(py_func))
613
620
 
614
621
    if not is_class:
689
696
    write_indented_lines(ident + "   ", fw, py_prop.__doc__)
690
697
    if py_prop.fset is None:
691
698
        fw(ident + "   (readonly)\n\n")
 
699
    else:
 
700
        fw("\n")
692
701
 
693
702
 
694
703
def pymodule2sphinx(basepath, module_name, module, title):
849
858
        elif value_type in (bool, int, float, str, tuple):
850
859
            # constant, not much fun we can do here except to list it.
851
860
            # TODO, figure out some way to document these!
852
 
            #fw(".. data:: %s\n\n" % attribute)
 
861
            fw(".. data:: %s\n\n" % attribute)
853
862
            write_indented_lines("   ", fw, "constant value %s" % repr(value), False)
854
863
            fw("\n")
855
864
        else:
910
919
 
911
920
    file.close()
912
921
 
 
922
# Changes in blender will force errors here
 
923
context_type_map = {
 
924
    "active_base": ("ObjectBase", False),
 
925
    "active_bone": ("EditBone", False),
 
926
    "active_object": ("Object", False),
 
927
    "active_operator": ("Operator", False),
 
928
    "active_pose_bone": ("PoseBone", False),
 
929
    "active_node": ("Node", False),
 
930
    "armature": ("Armature", False),
 
931
    "bone": ("Bone", False),
 
932
    "brush": ("Brush", False),
 
933
    "camera": ("Camera", False),
 
934
    "cloth": ("ClothModifier", False),
 
935
    "collision": ("CollisionModifier", False),
 
936
    "curve": ("Curve", False),
 
937
    "dynamic_paint": ("DynamicPaintModifier", False),
 
938
    "edit_bone": ("EditBone", False),
 
939
    "edit_image": ("Image", False),
 
940
    "edit_mask": ("Mask", False),
 
941
    "edit_movieclip": ("MovieClip", False),
 
942
    "edit_object": ("Object", False),
 
943
    "edit_text": ("Text", False),
 
944
    "editable_bones": ("EditBone", True),
 
945
    "fluid": ("FluidSimulationModifier", False),
 
946
    "image_paint_object": ("Object", False),
 
947
    "lamp": ("Lamp", False),
 
948
    "lattice": ("Lattice", False),
 
949
    "material": ("Material", False),
 
950
    "material_slot": ("MaterialSlot", False),
 
951
    "mesh": ("Mesh", False),
 
952
    "meta_ball": ("MetaBall", False),
 
953
    "object": ("Object", False),
 
954
    "particle_edit_object": ("Object", False),
 
955
    "particle_settings": ("ParticleSettings", False),
 
956
    "particle_system": ("ParticleSystem", False),
 
957
    "particle_system_editable": ("ParticleSystem", False),
 
958
    "pose_bone": ("PoseBone", False),
 
959
    "scene": ("Scene", False),
 
960
    "sculpt_object": ("Object", False),
 
961
    "selectable_bases": ("ObjectBase", True),
 
962
    "selectable_objects": ("Object", True),
 
963
    "selected_bases": ("ObjectBase", True),
 
964
    "selected_bones": ("EditBone", True),
 
965
    "selected_editable_bases": ("ObjectBase", True),
 
966
    "selected_editable_bones": ("EditBone", True),
 
967
    "selected_editable_objects": ("Object", True),
 
968
    "selected_editable_sequences": ("Sequence", True),
 
969
    "selected_nodes": ("Node", True),
 
970
    "selected_objects": ("Object", True),
 
971
    "selected_pose_bones": ("PoseBone", True),
 
972
    "selected_sequences": ("Sequence", True),
 
973
    "sequences": ("Sequence", True),
 
974
    "smoke": ("SmokeModifier", False),
 
975
    "soft_body": ("SoftBodyModifier", False),
 
976
    "speaker": ("Speaker", False),
 
977
    "texture": ("Texture", False),
 
978
    "texture_slot": ("MaterialTextureSlot", False),
 
979
    "texture_user": ("ID", False),
 
980
    "vertex_paint_object": ("Object", False),
 
981
    "visible_bases": ("ObjectBase", True),
 
982
    "visible_bones": ("EditBone", True),
 
983
    "visible_objects": ("Object", True),
 
984
    "visible_pose_bones": ("PoseBone", True),
 
985
    "weight_paint_object": ("Object", False),
 
986
    "world": ("World", False),
 
987
}
 
988
 
913
989
 
914
990
def pycontext2sphinx(basepath):
915
991
    # Only use once. very irregular
934
1010
        "image_context_dir",
935
1011
        "node_context_dir",
936
1012
        "text_context_dir",
 
1013
        "clip_context_dir",
 
1014
        "sequencer_context_dir",
937
1015
    )
938
1016
 
939
 
    # Changes in blender will force errors here
940
 
    type_map = {
941
 
        "active_base": ("ObjectBase", False),
942
 
        "active_bone": ("Bone", False),
943
 
        "active_object": ("Object", False),
944
 
        "active_operator": ("Operator", False),
945
 
        "active_pose_bone": ("PoseBone", False),
946
 
        "armature": ("Armature", False),
947
 
        "bone": ("Bone", False),
948
 
        "brush": ("Brush", False),
949
 
        "camera": ("Camera", False),
950
 
        "cloth": ("ClothModifier", False),
951
 
        "collision": ("CollisionModifier", False),
952
 
        "curve": ("Curve", False),
953
 
        "dynamic_paint": ("DynamicPaintModifier", False),
954
 
        "edit_bone": ("EditBone", False),
955
 
        "edit_image": ("Image", False),
956
 
        "edit_object": ("Object", False),
957
 
        "edit_text": ("Text", False),
958
 
        "editable_bones": ("EditBone", True),
959
 
        "fluid": ("FluidSimulationModifier", False),
960
 
        "image_paint_object": ("Object", False),
961
 
        "lamp": ("Lamp", False),
962
 
        "lattice": ("Lattice", False),
963
 
        "material": ("Material", False),
964
 
        "material_slot": ("MaterialSlot", False),
965
 
        "mesh": ("Mesh", False),
966
 
        "meta_ball": ("MetaBall", False),
967
 
        "object": ("Object", False),
968
 
        "particle_edit_object": ("Object", False),
969
 
        "particle_system": ("ParticleSystem", False),
970
 
        "particle_system_editable": ("ParticleSystem", False),
971
 
        "pose_bone": ("PoseBone", False),
972
 
        "scene": ("Scene", False),
973
 
        "sculpt_object": ("Object", False),
974
 
        "selectable_bases": ("ObjectBase", True),
975
 
        "selectable_objects": ("Object", True),
976
 
        "selected_bases": ("ObjectBase", True),
977
 
        "selected_bones": ("Bone", True),
978
 
        "selected_editable_bases": ("ObjectBase", True),
979
 
        "selected_editable_bones": ("Bone", True),
980
 
        "selected_editable_objects": ("Object", True),
981
 
        "selected_editable_sequences": ("Sequence", True),
982
 
        "selected_nodes": ("Node", True),
983
 
        "selected_objects": ("Object", True),
984
 
        "selected_pose_bones": ("PoseBone", True),
985
 
        "selected_sequences": ("Sequence", True),
986
 
        "sequences": ("Sequence", True),
987
 
        "smoke": ("SmokeModifier", False),
988
 
        "soft_body": ("SoftBodyModifier", False),
989
 
        "speaker": ("Speaker", False),
990
 
        "texture": ("Texture", False),
991
 
        "texture_slot": ("MaterialTextureSlot", False),
992
 
        "texture_user": ("ID", False),
993
 
        "vertex_paint_object": ("Object", False),
994
 
        "visible_bases": ("ObjectBase", True),
995
 
        "visible_bones": ("Object", True),
996
 
        "visible_objects": ("Object", True),
997
 
        "visible_pose_bones": ("PoseBone", True),
998
 
        "weight_paint_object": ("Object", False),
999
 
        "world": ("World", False),
1000
 
    }
1001
 
 
1002
1017
    unique = set()
1003
1018
    blend_cdll = ctypes.CDLL("")
1004
1019
    for ctx_str in context_strings:
1012
1027
        while char_array[i] is not None:
1013
1028
            member = ctypes.string_at(char_array[i]).decode(encoding="ascii")
1014
1029
            fw(".. data:: %s\n\n" % member)
1015
 
            member_type, is_seq = type_map[member]
 
1030
            member_type, is_seq = context_type_map[member]
1016
1031
            fw("   :type: %s :class:`bpy.types.%s`\n\n" % ("sequence of " if is_seq else "", member_type))
1017
1032
            unique.add(member)
1018
1033
            i += 1
1020
1035
    # generate typemap...
1021
1036
    # for member in sorted(unique):
1022
1037
    #     print('        "%s": ("", False),' % member)
1023
 
    if len(type_map) > len(unique):
1024
 
        raise Exception("Some types are not used: %s" % str([member for member in type_map if member not in unique]))
 
1038
    if len(context_type_map) > len(unique):
 
1039
        raise Exception("Some types are not used: %s" % str([member for member in context_type_map if member not in unique]))
1025
1040
    else:
1026
1041
        pass  # will have raised an error above
1027
1042
 
1245
1260
            bases = list(reversed(struct.get_bases()))
1246
1261
 
1247
1262
            # props
1248
 
            lines[:] = []
 
1263
            del lines[:]
1249
1264
 
1250
1265
            if _BPY_STRUCT_FAKE:
1251
1266
                descr_items = [(key, descr) for key, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()) if not key.startswith("__")]
1276
1291
                fw("\n")
1277
1292
 
1278
1293
            # funcs
1279
 
            lines[:] = []
 
1294
            del lines[:]
1280
1295
 
1281
1296
            if _BPY_STRUCT_FAKE:
1282
1297
                for key, descr in descr_items:
1299
1314
                    fw(line)
1300
1315
                fw("\n")
1301
1316
 
1302
 
            lines[:] = []
 
1317
            del lines[:]
1303
1318
 
1304
1319
        if struct.references:
1305
1320
            # use this otherwise it gets in the index for a normal heading.
1308
1323
            fw(".. hlist::\n")
1309
1324
            fw("   :columns: 2\n\n")
1310
1325
 
 
1326
            # context does its own thing
 
1327
            # "active_base": ("ObjectBase", False),
 
1328
            for ref_attr, (ref_type, ref_is_seq) in sorted(context_type_map.items()):
 
1329
                if ref_type == struct_id:
 
1330
                    fw("   * :mod:`bpy.context.%s`\n" % ref_attr)
 
1331
            del ref_attr, ref_type, ref_is_seq
 
1332
 
1311
1333
            for ref in struct.references:
1312
1334
                ref_split = ref.split(".")
1313
1335
                if len(ref_split) > 2:
1459
1481
    file.close()
1460
1482
 
1461
1483
 
 
1484
def execfile(filepath):
 
1485
    global_namespace = {"__file__": filepath, "__name__": "__main__"}
 
1486
    file_handle = open(filepath)
 
1487
    exec(compile(file_handle.read(), filepath, 'exec'), global_namespace)
 
1488
    file_handle.close()
 
1489
 
 
1490
 
1462
1491
def write_rst_contents(basepath):
1463
1492
    '''
1464
1493
    Write the rst file of the main page, needed for sphinx (index.html)
1519
1548
        "mathutils", "mathutils.geometry", "mathutils.noise",
1520
1549
        # misc
1521
1550
        "bgl", "blf", "gpu", "aud", "bpy_extras",
1522
 
        # bmesh
1523
 
        "bmesh", "bmesh.types", "bmesh.utils",
 
1551
        # bmesh, submodules are in own page
 
1552
        "bmesh",
1524
1553
        )
1525
1554
 
1526
1555
    for mod in standalone_modules:
1527
1556
        if mod not in EXCLUDE_MODULES:
1528
1557
            fw("   %s\n\n" % mod)
1529
1558
 
 
1559
    # special case, this 'bmesh.ops.rst' is extracted from C source
 
1560
    if "bmesh.ops" not in EXCLUDE_MODULES:
 
1561
        execfile(os.path.join(SCRIPT_DIR, "rst_from_bmesh_opdefines.py"))
 
1562
 
1530
1563
    # game engine
1531
1564
    if "bge" not in EXCLUDE_MODULES:
1532
1565
        fw(title_string("Game Engine Modules", "=", double=True))
1679
1712
 
1680
1713
    # TODO put this docs in blender's code and use import as per modules above
1681
1714
    handwritten_modules = [
1682
 
        "bge.types",
1683
1715
        "bge.logic",
1684
1716
        "bge.render",
1685
1717
        "bge.texture",
1688
1720
        "bgl",  # "Blender OpenGl wrapper"
1689
1721
        "gpu",  # "GPU Shader Module"
1690
1722
 
 
1723
        "bmesh.ops",  # generated by rst_from_bmesh_opdefines.py
 
1724
 
1691
1725
        # includes...
1692
1726
        "include__bmesh",
1693
1727
    ]
1696
1730
            # copy2 keeps time/date stamps
1697
1731
            shutil.copy2(os.path.join(RST_DIR, "%s.rst" % mod_name), basepath)
1698
1732
 
 
1733
    if "bge.types" not in EXCLUDE_MODULES:
 
1734
        shutil.copy2(os.path.join(RST_DIR, "bge.types.rst"), basepath)
 
1735
 
 
1736
        bge_types_dir = os.path.join(RST_DIR, "bge_types")
 
1737
 
 
1738
        for i in os.listdir(bge_types_dir):
 
1739
            shutil.copy2(os.path.join(bge_types_dir, i), basepath)
 
1740
 
1699
1741
    # changelog
1700
1742
    shutil.copy2(os.path.join(RST_DIR, "change_log.rst"), basepath)
1701
1743
 
 
1744
    # copy images, could be smarter but just glob for now.
 
1745
    for f in os.listdir(RST_DIR):
 
1746
        if f.endswith(".png"):
 
1747
            shutil.copy2(os.path.join(RST_DIR, f), basepath)
 
1748
 
1702
1749
 
1703
1750
def rna2sphinx(basepath):
1704
1751
 
1778
1825
            refactored_logfile.write("%-12s %s\n             %s\n" % log)
1779
1826
 
1780
1827
 
 
1828
def monkey_patch():
 
1829
    filepath = os.path.join(SCRIPT_DIR, "sphinx_doc_gen_monkeypatch.py")
 
1830
    global_namespace = {"__file__": filepath, "__name__": "__main__"}
 
1831
    file = open(filepath, 'rb')
 
1832
    exec(compile(file.read(), filepath, 'exec'), global_namespace)
 
1833
    file.close()
 
1834
 
 
1835
 
1781
1836
def main():
1782
1837
 
 
1838
    # first monkey patch to load in fake members
 
1839
    monkey_patch()
 
1840
 
1783
1841
    # eventually, create the dirs
1784
1842
    for dir_path in [ARGS.output_dir, SPHINX_IN]:
1785
1843
        if not os.path.exists(dir_path):