tmaq
/
tornavis
1
0
Fork 0
Code Issues 2 Pull Requests 29 Packages Projects 24 Releases Wiki Activity

- generate sphinx docs for bpy_extras module 

- add in support to doc generator for automatically generating docs for submodules.
This commit is contained in:
Campbell Barton 2011-05-28 07:47:58 +00:00
parent 20ae95422e
commit ecf2d1ff4e
6 changed files with 128 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
doc/python_api/sphinx_doc_gen.py
View File

@ -34,7 +34,8 @@ For HTML generation
- 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 @@ def write_indented_lines(ident, fn, text, strip=True):
'''
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 @@ def pyfunc2sphinx(ident, fw, identifier, py_func, is_class=True):
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 @@ def py_descr2sphinx(ident, fw, descr, module_name, type_name, identifier):
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 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
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 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
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 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
if descr.__doc__:
fw(".. data:: %s\n\n" % key)
write_indented_lines(" ", fw, descr.__doc__, False)
attribute_set.add(key)
fw("\n")
attribute_set.add(key)
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 @@ def rna2sphinx(BASEPATH):
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 @@ def rna2sphinx(BASEPATH):
# 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

12
release/scripts/modules/bpy_extras/image_utils.py
View File

@ -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

14
release/scripts/modules/bpy_extras/io_utils.py
View File

@ -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

8
release/scripts/modules/bpy_extras/mesh_utils.py
View File

@ -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):
'''

6
release/scripts/modules/bpy_extras/object_utils.py
View File

@ -18,6 +18,12 @@
# <pep8 compliant>
__all__ = (
"add_object_align_init",
"object_data_add",
)
import bpy
import mathutils

12
release/scripts/modules/bpy_extras/view3d_utils.py
View File

@ -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 @@ def region_2d_to_vector_3d(region, rv3d, coord):
:type region: :class:`Region`
:arg rv3d: 3D region data, typically bpy.context.space_data.region_3d.
:type rv3d: :class:`RegionView3D`
:arg coord: 2d coordinates relative to the region;
:arg coord: 2d coordinates relative to the region:
(event.mouse_region_x, event.mouse_region_y) for example.
:type coord: 2d vector
:return: normalized 3d vector.
@ -44,7 +50,9 @@ def region_2d_to_vector_3d(region, rv3d, coord):
-0.5
))
w = (out[0] * persinv[0][3]) + (out[1] * persinv[1][3]) + (out[2] * persinv[2][3]) + persinv[3][3]
w = (out[0] * persinv[0][3]) + \
(out[1] * persinv[1][3]) + \
(out[2] * persinv[2][3]) + persinv[3][3]
return ((out * persinv) / w) - rv3d.view_matrix.inverted()[3].xyz
else: