diff options
author | Tamito Kajiyama <rd6t-kjym@asahi-net.or.jp> | 2011-09-17 22:54:16 +0400 |
---|---|---|
committer | Tamito Kajiyama <rd6t-kjym@asahi-net.or.jp> | 2011-09-17 22:54:16 +0400 |
commit | 70821c6b24f19acd7263fadf161b94611b53273f (patch) | |
tree | a662f3a9b1dc2db824699888acb7cedf6749eb89 /doc/python_api | |
parent | f24255b5a03f68a2ef4e09eb55d93dc21a1f44c0 (diff) | |
parent | e53c4dae546f9550d6a4e79ae87c3dee9ac7b650 (diff) |
Merged changes in the trunk up to revision 40299.
Diffstat (limited to 'doc/python_api')
-rw-r--r-- | doc/python_api/examples/bpy.types.ID.user_clear.1.py | 2 | ||||
-rw-r--r-- | doc/python_api/rst/info_tips_and_tricks.rst | 8 | ||||
-rw-r--r-- | doc/python_api/sphinx_doc_gen.py | 57 | ||||
-rwxr-xr-x | doc/python_api/sphinx_doc_gen.sh | 33 |
4 files changed, 85 insertions, 15 deletions
diff --git a/doc/python_api/examples/bpy.types.ID.user_clear.1.py b/doc/python_api/examples/bpy.types.ID.user_clear.1.py index 68c35caa7d4..239ed41c66c 100644 --- a/doc/python_api/examples/bpy.types.ID.user_clear.1.py +++ b/doc/python_api/examples/bpy.types.ID.user_clear.1.py @@ -1,6 +1,4 @@ """ -User Clear -++++++++++ This function is for advanced use only, misuse can crash blender since the user count is used to prevent data being removed when it is used. """ diff --git a/doc/python_api/rst/info_tips_and_tricks.rst b/doc/python_api/rst/info_tips_and_tricks.rst index 2bcb1e74c84..f88be5de3a8 100644 --- a/doc/python_api/rst/info_tips_and_tricks.rst +++ b/doc/python_api/rst/info_tips_and_tricks.rst @@ -24,6 +24,14 @@ There are 3 main uses for the terminal, these are: For Linux and OSX users this means starting the terminal first, then running blender from within it. On Windows the terminal can be enabled from the help menu. +Show All Operators +================== + +While blender logs operators in the Info space, this only reports operators with the ``REGISTER`` option enabeld so as not to flood the Info view with calls to ``bpy.ops.view3d.smoothview`` and ``bpy.ops.view3d.zoom``. + +However, for testing it can be useful to see **every** operator called in a terminal, do this by enabling the debug option either by passing the ``--debug`` argument when starting blender or by setting :mod:`bpy.app.debug` to True while blender is running. + + Use an External Editor ====================== diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index df17c54b55f..4e17fcd8dda 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -76,7 +76,7 @@ else: "bpy.props", "bpy.utils", "bpy.context", - "bpy.types", # supports filtering + # "bpy.types", # supports filtering "bpy.ops", # supports filtering "bpy_extras", "bge", @@ -88,7 +88,7 @@ else: "Freestyle", ) - FILTER_BPY_TYPES = ("bpy_struct", "Panel", "ID") # allow + FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID") # allow FILTER_BPY_OPS = ("import.scene", ) # allow # for quick rebuilds @@ -629,6 +629,30 @@ def pycontext2sphinx(BASEPATH): file.close() +def pyrna_enum2sphinx(prop, use_empty_descriptions=False): + """ write a bullet point list of enum + descrptons + """ + + if use_empty_descriptions: + ok = True + else: + ok = False + for identifier, name, description in prop.enum_items: + if description: + ok = True + break + + if ok: + return "".join(["* ``%s`` %s.\n" % + (identifier, + ", ".join(val for val in (name, description) if val), + ) + for identifier, name, description in prop.enum_items + ]) + else: + return "" + + def pyrna2sphinx(BASEPATH): """ bpy.types and bpy.ops """ @@ -656,8 +680,22 @@ def pyrna2sphinx(BASEPATH): kwargs["collection_id"] = _BPY_PROP_COLLECTION_ID type_descr = prop.get_type_description(**kwargs) - if prop.name or prop.description: - fw(ident + ":%s%s: %s\n" % (id_name, identifier, ", ".join(val for val in (prop.name, prop.description) if val))) + + enum_text = pyrna_enum2sphinx(prop) + + if prop.name or prop.description or enum_text: + fw(ident + ":%s%s:\n\n" % (id_name, identifier)) + + if prop.name or prop.description: + fw(ident + " " + ", ".join(val for val in (prop.name, prop.description) if val) + "\n\n") + + # special exception, cant use genric code here for enums + if enum_text: + write_indented_lines(ident + " ", fw, enum_text) + fw("\n") + del enum_text + # end enum exception + fw(ident + ":%s%s: %s\n" % (id_type, identifier, type_descr)) def write_struct(struct): @@ -735,6 +773,16 @@ def pyrna2sphinx(BASEPATH): fw(" .. attribute:: %s\n\n" % prop.identifier) if prop.description: fw(" %s\n\n" % prop.description) + + # special exception, cant use genric code here for enums + if prop.type == "enum": + enum_text = pyrna_enum2sphinx(prop) + if enum_text: + write_indented_lines(" ", fw, enum_text) + fw("\n") + del enum_text + # end enum exception + fw(" :type: %s\n\n" % type_descr) # python attributes @@ -758,6 +806,7 @@ def pyrna2sphinx(BASEPATH): elif func.return_values: # multiple return values fw(" :return (%s):\n" % ", ".join(prop.identifier for prop in func.return_values)) for prop in func.return_values: + # TODO, pyrna_enum2sphinx for multiple return values... actually dont think we even use this but still!!! type_descr = prop.get_type_description(as_ret=True, class_fmt=":class:`%s`", collection_id=_BPY_PROP_COLLECTION_ID) descr = prop.description if not descr: diff --git a/doc/python_api/sphinx_doc_gen.sh b/doc/python_api/sphinx_doc_gen.sh index ea55fbb3907..307476d9a92 100755 --- a/doc/python_api/sphinx_doc_gen.sh +++ b/doc/python_api/sphinx_doc_gen.sh @@ -9,6 +9,10 @@ # disable for testing DO_UPLOAD=true +DO_EXE_BLENDER=true +DO_OUT_HTML=true +DO_OUT_PDF=true + BLENDER="./blender.bin" SSH_USER="ideasman42" @@ -36,28 +40,39 @@ fi SSH_UPLOAD_FULL=$SSH_UPLOAD/"blender_python_api_"$BLENDER_VERSION -SPHINXBASE=doc/python_api/ +SPHINXBASE=doc/python_api # ---------------------------------------------------------------------------- # Generate reStructuredText (blender/python only) -# dont delete existing docs, now partial updates are used for quick builds. -$BLENDER --background --factory-startup --python $SPHINXBASE/sphinx_doc_gen.py +if $DO_EXE_BLENDER ; then + # dont delete existing docs, now partial updates are used for quick builds. + $BLENDER --background --factory-startup --python $SPHINXBASE/sphinx_doc_gen.py +fi # ---------------------------------------------------------------------------- # Generate HTML (sphinx) -sphinx-build -n -b html $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out +if $DO_OUT_HTML ; then + # sphinx-build -n -b html $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out + + # annoying bug in sphinx makes it very slow unless we do this. should report. + cd $SPHINXBASE + sphinx-build -n -b html sphinx-in sphinx-out + cd - +fi # ---------------------------------------------------------------------------- # Generate PDF (sphinx/laytex) -sphinx-build -n -b latex $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out -make -C $SPHINXBASE/sphinx-out -mv $SPHINXBASE/sphinx-out/contents.pdf $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf +if $DO_OUT_PDF ; then + sphinx-build -n -b latex $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out + make -C $SPHINXBASE/sphinx-out + mv $SPHINXBASE/sphinx-out/contents.pdf $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf +fi # ---------------------------------------------------------------------------- # Upload to blender servers, comment this section for testing @@ -85,5 +100,5 @@ fi echo "" echo "Finished! view the docs from: " -echo " html:" $SPHINXBASE/sphinx-out/contents.html -echo " pdf:" $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf +if $DO_OUT_HTML ; then echo " html:" $SPHINXBASE/sphinx-out/contents.html ; fi +if $DO_OUT_PDF ; then echo " pdf:" $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf ; fi |