diff options
author | Campbell Barton <ideasman42@gmail.com> | 2011-09-15 20:15:24 +0400 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2011-09-15 20:15:24 +0400 |
commit | e2818f1b926b779b1d59010aaa5c4e625c0877d5 (patch) | |
tree | b3dd25c0d82e43bde60938b85ce5b9ac5532223d /doc | |
parent | 2f50579d9a008735b268f134428035a7deaa7372 (diff) |
- include enum names and descriptions in sphinx generated documentation
- add descriptions for operator bl_options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/python_api/examples/bpy.types.ID.user_clear.1.py | 2 | ||||
-rw-r--r-- | doc/python_api/sphinx_doc_gen.py | 57 | ||||
-rwxr-xr-x | doc/python_api/sphinx_doc_gen.sh | 33 |
3 files changed, 77 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/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index ac2a498efc2..dec4a7a4c99 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", @@ -87,7 +87,7 @@ else: "mathutils.geometry", ) - 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 @@ -621,6 +621,30 @@ def pycontext2sphinx(BASEPATH): file.close() +def pyrna_enum2sphinx(prop, use_empty_descriptions=True): + """ 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 """ @@ -648,8 +672,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): @@ -727,6 +765,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 @@ -750,6 +798,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 |