[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [36969] trunk/blender: - generate sphinx docs for bpy_extras module
Campbell Barton
ideasman42 at gmail.com
Sat May 28 09:47:59 CEST 2011
Revision: 36969
http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=36969
Author: campbellbarton
Date: 2011-05-28 07:47:58 +0000 (Sat, 28 May 2011)
Log Message:
-----------
- generate sphinx docs for bpy_extras module
- add in support to doc generator for automatically generating docs for submodules.
Modified Paths:
--------------
trunk/blender/doc/python_api/sphinx_doc_gen.py
trunk/blender/release/scripts/modules/bpy_extras/image_utils.py
trunk/blender/release/scripts/modules/bpy_extras/io_utils.py
trunk/blender/release/scripts/modules/bpy_extras/mesh_utils.py
trunk/blender/release/scripts/modules/bpy_extras/object_utils.py
trunk/blender/release/scripts/modules/bpy_extras/view3d_utils.py
Modified: trunk/blender/doc/python_api/sphinx_doc_gen.py
===================================================================
--- trunk/blender/doc/python_api/sphinx_doc_gen.py 2011-05-28 07:15:27 UTC (rev 36968)
+++ trunk/blender/doc/python_api/sphinx_doc_gen.py 2011-05-28 07:47:58 UTC (rev 36969)
@@ -34,7 +34,8 @@
- Generate html docs by running...
- sphinx-build doc/python_api/sphinx-in doc/python_api/sphinx-out
+ cd doc/python_api
+ sphinx-build sphinx-in sphinx-out
assuming that you have sphinx 1.0.7 installed
@@ -204,10 +205,24 @@
'''
if text is None:
return
- for l in text.split("\n"):
- if strip:
- fn(ident + l.strip() + "\n")
- else:
+
+ lines = text.split("\n")
+
+ # strip empty lines from the start/end
+ while lines and not lines[0].strip():
+ del lines[0]
+ while lines and not lines[-1].strip():
+ del lines[-1]
+
+ if strip:
+ ident_strip = 1000
+ for l in lines:
+ if l.strip():
+ ident_strip = min(ident_strip, len(l) - len(l.lstrip()))
+ for l in lines:
+ fn(ident + l[ident_strip:] + "\n")
+ else:
+ for l in lines:
fn(ident + l + "\n")
@@ -252,7 +267,7 @@
fw(ident + ".. %s:: %s%s\n\n" % (func_type, identifier, arg_str))
if py_func.__doc__:
- write_indented_lines(ident + " ", fw, py_func.__doc__.strip())
+ write_indented_lines(ident + " ", fw, py_func.__doc__)
fw("\n")
@@ -267,8 +282,10 @@
if type(descr) == GetSetDescriptorType:
fw(ident + ".. attribute:: %s\n\n" % identifier)
write_indented_lines(ident + " ", fw, doc, False)
+ fw("\n")
elif type(descr) in (MethodDescriptorType, ClassMethodDescriptorType):
write_indented_lines(ident, fw, doc, False)
+ fw("\n")
else:
raise TypeError("type was not GetSetDescriptorType, MethodDescriptorType or ClassMethodDescriptorType")
@@ -316,11 +333,17 @@
attribute_set = set()
filepath = os.path.join(BASEPATH, module_name + ".rst")
+ module_all = getattr(module, "__all__", None)
+ module_dir = sorted(dir(module))
+
+ if module_all:
+ module_dir = module_all
+
file = open(filepath, "w")
fw = file.write
- write_title(fw, title, "=")
+ write_title(fw, "%s (%s)" % (title, module_name), "=")
fw(".. module:: %s\n\n" % module_name)
@@ -331,6 +354,37 @@
write_example_ref("", fw, module_name)
+ # write submodules
+ # we could also scan files but this ensures __all__ is used correctly
+ if module_all is not None:
+ submod_name = None
+ submod = None
+ submod_ls = []
+ for submod_name in module_all:
+ ns = {}
+ exec_str = "from %s import %s as submod" % (module.__name__, submod_name)
+ print(exec_str)
+ exec(exec_str, ns, ns)
+ submod = ns["submod"]
+ print(submod)
+ if type(submod) == types.ModuleType:
+ submod_ls.append((submod_name, submod))
+
+ del submod_name
+ del submod
+
+ if submod_ls:
+ fw(".. toctree::\n")
+ fw(" :maxdepth: 1\n\n")
+
+ for submod_name, submod in submod_ls:
+ submod_name_full = "%s.%s" % (module_name, submod_name)
+ fw(" %s.rst\n\n" % submod_name_full)
+
+ pymodule2sphinx(BASEPATH, submod_name_full, submod, "%s submodule" % module_name)
+ del submod_ls
+ # done writing submodules!
+
# write members of the module
# only tested with PyStructs which are not exactly modules
for key, descr in sorted(type(module).__dict__.items()):
@@ -348,15 +402,15 @@
if descr.__doc__:
fw(".. data:: %s\n\n" % key)
write_indented_lines(" ", fw, descr.__doc__, False)
+ fw("\n")
attribute_set.add(key)
- fw("\n")
+
del key, descr
classes = []
- for attribute in sorted(dir(module)):
+ for attribute in module_dir:
if not attribute.startswith("_"):
-
if attribute in attribute_set:
continue
@@ -972,6 +1026,8 @@
fw(" blf.rst\n\n")
if "aud" not in EXCLUDE_MODULES:
fw(" aud.rst\n\n")
+ if "bpy_extras" not in EXCLUDE_MODULES:
+ fw(" bpy_extras.rst\n\n")
# game engine
if "bge" not in EXCLUDE_MODULES:
@@ -1068,41 +1124,45 @@
# python modules
if "bpy.utils" not in EXCLUDE_MODULES:
from bpy import utils as module
- pymodule2sphinx(BASEPATH, "bpy.utils", module, "Utilities (bpy.utils)")
+ pymodule2sphinx(BASEPATH, "bpy.utils", module, "Utilities")
if "bpy.path" not in EXCLUDE_MODULES:
from bpy import path as module
- pymodule2sphinx(BASEPATH, "bpy.path", module, "Path Utilities (bpy.path)")
+ pymodule2sphinx(BASEPATH, "bpy.path", module, "Path Utilities")
+ if "bpy_extras" not in EXCLUDE_MODULES:
+ import bpy_extras as module
+ pymodule2sphinx(BASEPATH, "bpy_extras", module, "Extra Utilities")
+
# C modules
if "bpy.app" not in EXCLUDE_MODULES:
from bpy import app as module
- pymodule2sphinx(BASEPATH, "bpy.app", module, "Application Data (bpy.app)")
+ pymodule2sphinx(BASEPATH, "bpy.app", module, "Application Data")
if "bpy.props" not in EXCLUDE_MODULES:
from bpy import props as module
- pymodule2sphinx(BASEPATH, "bpy.props", module, "Property Definitions (bpy.props)")
+ pymodule2sphinx(BASEPATH, "bpy.props", module, "Property Definitions")
if "mathutils" not in EXCLUDE_MODULES:
import mathutils as module
- pymodule2sphinx(BASEPATH, "mathutils", module, "Math Types & Utilities (mathutils)")
+ pymodule2sphinx(BASEPATH, "mathutils", module, "Math Types & Utilities")
if "mathutils.geometry" not in EXCLUDE_MODULES:
import mathutils.geometry as module
- pymodule2sphinx(BASEPATH, "mathutils.geometry", module, "Geometry Utilities (mathutils.geometry)")
+ pymodule2sphinx(BASEPATH, "mathutils.geometry", module, "Geometry Utilities")
if "mathutils.geometry" not in EXCLUDE_MODULES:
import blf as module
- pymodule2sphinx(BASEPATH, "blf", module, "Font Drawing (blf)")
+ pymodule2sphinx(BASEPATH, "blf", module, "Font Drawing")
# XXX TODO
#import bgl as module
- #pymodule2sphinx(BASEPATH, "bgl", module, "Blender OpenGl wrapper (bgl)")
+ #pymodule2sphinx(BASEPATH, "bgl", module, "Blender OpenGl wrapper")
#del module
if "aud" not in EXCLUDE_MODULES:
import aud as module
- pymodule2sphinx(BASEPATH, "aud", module, "Audio System (aud)")
+ pymodule2sphinx(BASEPATH, "aud", module, "Audio System")
del module
## game engine
Modified: trunk/blender/release/scripts/modules/bpy_extras/image_utils.py
===================================================================
--- trunk/blender/release/scripts/modules/bpy_extras/image_utils.py 2011-05-28 07:15:27 UTC (rev 36968)
+++ trunk/blender/release/scripts/modules/bpy_extras/image_utils.py 2011-05-28 07:47:58 UTC (rev 36969)
@@ -18,10 +18,20 @@
# <pep8 compliant>
+__all__ = (
+ "image_load",
+)
+
def image_load(filepath, dirpath, place_holder=False, recursive=False, convert_callback=None):
import bpy
+ import os
+
try:
return bpy.data.images.load(filepath)
except RuntimeError:
- return bpy.data.images.new("Untitled", 128, 128)
+ if place_holder:
+ image = bpy.data.images.new(os.path.basename(filepath), 128, 128)
+ # allow the path to be resolved later
+ image.filepath = filepath
+ return image
Modified: trunk/blender/release/scripts/modules/bpy_extras/io_utils.py
===================================================================
--- trunk/blender/release/scripts/modules/bpy_extras/io_utils.py 2011-05-28 07:15:27 UTC (rev 36968)
+++ trunk/blender/release/scripts/modules/bpy_extras/io_utils.py 2011-05-28 07:47:58 UTC (rev 36969)
@@ -18,6 +18,20 @@
# <pep8 compliant>
+__all__ = (
+ "ExportHelper",
+ "ImportHelper",
+ "axis_conversion",
+ "load_image",
+ "create_derived_objects",
+ "free_derived_objects",
+ "unpack_list",
+ "unpack_face_list",
+ "path_reference",
+ "path_reference_copy",
+ "path_reference_mode",
+)
+
import bpy
from bpy.props import StringProperty, BoolProperty, EnumProperty
Modified: trunk/blender/release/scripts/modules/bpy_extras/mesh_utils.py
===================================================================
--- trunk/blender/release/scripts/modules/bpy_extras/mesh_utils.py 2011-05-28 07:15:27 UTC (rev 36968)
+++ trunk/blender/release/scripts/modules/bpy_extras/mesh_utils.py 2011-05-28 07:47:58 UTC (rev 36969)
@@ -18,6 +18,14 @@
# <pep8 compliant>
+__all__ = (
+ "mesh_linked_faces",
+ "edge_face_count_dict",
+ "edge_face_count",
+ "edge_loops_from_faces",
+ "edge_loops_from_edges",
+ "ngon_tesselate",
+)
def mesh_linked_faces(mesh):
'''
Modified: trunk/blender/release/scripts/modules/bpy_extras/object_utils.py
===================================================================
--- trunk/blender/release/scripts/modules/bpy_extras/object_utils.py 2011-05-28 07:15:27 UTC (rev 36968)
+++ trunk/blender/release/scripts/modules/bpy_extras/object_utils.py 2011-05-28 07:47:58 UTC (rev 36969)
@@ -18,6 +18,12 @@
# <pep8 compliant>
+__all__ = (
+ "add_object_align_init",
+ "object_data_add",
+)
+
+
import bpy
import mathutils
Modified: trunk/blender/release/scripts/modules/bpy_extras/view3d_utils.py
===================================================================
--- trunk/blender/release/scripts/modules/bpy_extras/view3d_utils.py 2011-05-28 07:15:27 UTC (rev 36968)
+++ trunk/blender/release/scripts/modules/bpy_extras/view3d_utils.py 2011-05-28 07:47:58 UTC (rev 36969)
@@ -18,6 +18,12 @@
# <pep8 compliant>
+__all__ = (
+ "region_2d_to_vector_3d",
+ "region_2d_to_location_3d",
+ "location_3d_to_region_2d",
+ "location_3d_to_region_2d",
+)
def region_2d_to_vector_3d(region, rv3d, coord):
"""
@@ -28,7 +34,7 @@
:type region: :class:`Region`
:arg rv3d: 3D region data, typically bpy.context.space_data.region_3d.
:type rv3d: :class:`RegionView3D`
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list