[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [26178] trunk/blender: initial sphinx doc generation support for python and C modules.
Campbell Barton
ideasman42 at gmail.com
Fri Jan 22 03:04:29 CET 2010
Revision: 26178
http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=26178
Author: campbellbarton
Date: 2010-01-22 03:04:25 +0100 (Fri, 22 Jan 2010)
Log Message:
-----------
initial sphinx doc generation support for python and C modules.
python modules bpy.app, bpy.utils are now included in docs.
C defined python module bpy.props has its docstrings extracted and written directly into sphinx docs since the C methods cant be inspected.
added docstrings to bpy.props and improved some in bpy.utils.
will update online docs tomorrow.
Modified Paths:
--------------
trunk/blender/release/scripts/modules/bpy/app.py
trunk/blender/release/scripts/modules/bpy/utils.py
trunk/blender/source/blender/python/intern/bpy_props.c
trunk/blender/source/blender/python/sphinx_doc_gen.py
Modified: trunk/blender/release/scripts/modules/bpy/app.py
===================================================================
--- trunk/blender/release/scripts/modules/bpy/app.py 2010-01-22 01:30:06 UTC (rev 26177)
+++ trunk/blender/release/scripts/modules/bpy/app.py 2010-01-22 02:04:25 UTC (rev 26178)
@@ -18,6 +18,27 @@
# <pep8 compliant>
+"""
+This module contains application values that remain unchanged during runtime.
+
+.. data:: version
+
+ The Blender version as a tuple of 3 numbers. eg. (2, 50, 11)
+
+
+.. data:: version_string
+
+ The Blender version formatted as a string.
+
+.. data:: home
+
+ The blender home directory, normally matching $HOME
+
+.. data:: binary_path
+
+ The location of blenders executable, useful for utilities that spawn new instances.
+
+"""
# constants
import _bpy
version = _bpy._VERSION
Modified: trunk/blender/release/scripts/modules/bpy/utils.py
===================================================================
--- trunk/blender/release/scripts/modules/bpy/utils.py 2010-01-22 01:30:06 UTC (rev 26177)
+++ trunk/blender/release/scripts/modules/bpy/utils.py 2010-01-22 02:04:25 UTC (rev 26178)
@@ -18,13 +18,18 @@
# <pep8 compliant>
-import bpy
-import os
+"""
+This module contains utility functions spesific to blender but
+not assosiated with blenders internal data.
+"""
+import bpy as _bpy
+import os as _os
+
def expandpath(path):
if path.startswith("//"):
- return os.path.join(os.path.dirname(bpy.data.filename), path[2:])
+ return _os.path.join(_os.path.dirname(_bpy.data.filename), path[2:])
return path
@@ -47,21 +52,23 @@
def clean_name(name, replace="_"):
- '''
+ """
+ Returns a name with characters replaced that may cause problems under various circumstances, such as writing to a file.
All characters besides A-Z/a-z, 0-9 are replaced with "_"
or the replace argumet if defined.
- '''
+ """
for ch in _unclean_chars:
name = name.replace(ch, replace)
return name
def display_name(name):
- '''
- Only capitalize all lowercase names, mixed case use them as is.
- should work with filenames and module names.
- '''
- name_base = os.path.splitext(name)[0]
+ """
+ Creates a display string from name to be used menus and the user interface.
+ Capitalize the first letter in all lowercase names, mixed case names are kept as is.
+ Intended for use with filenames and module names.
+ """
+ name_base = _os.path.splitext(name)[0]
# string replacements
name_base = name_base.replace("_colon_", ":")
@@ -75,39 +82,44 @@
# base scripts
-_scripts = os.path.join(os.path.dirname(__file__), os.path.pardir, os.path.pardir)
-_scripts = (os.path.normpath(_scripts), )
+_scripts = _os.path.join(_os.path.dirname(__file__), _os.path.pardir, _os.path.pardir)
+_scripts = (_os.path.normpath(_scripts), )
def script_paths(*args):
+ """
+ Returns a list of valid script paths from the home directory and user preferences.
+
+ Accepts any number of string arguments which are joined to make a path.
+ """
scripts = list(_scripts)
# add user scripts dir
- user_script_path = bpy.context.user_preferences.filepaths.python_scripts_directory
+ user_script_path = _bpy.context.user_preferences.filepaths.python_scripts_directory
if not user_script_path:
# XXX - WIN32 needs checking, perhaps better call a blender internal function.
- user_script_path = os.path.join(os.path.expanduser("~"), ".blender", "scripts")
+ user_script_path = _os.path.join(_os.path.expanduser("~"), ".blender", "scripts")
- user_script_path = os.path.normpath(user_script_path)
+ user_script_path = _os.path.normpath(user_script_path)
- if user_script_path not in scripts and os.path.isdir(user_script_path):
+ if user_script_path not in scripts and _os.path.isdir(user_script_path):
scripts.append(user_script_path)
if not args:
return scripts
- subdir = os.path.join(*args)
+ subdir = _os.path.join(*args)
script_paths = []
for path in scripts:
- path_subdir = os.path.join(path, subdir)
- if os.path.isdir(path_subdir):
+ path_subdir = _os.path.join(path, subdir)
+ if _os.path.isdir(path_subdir):
script_paths.append(path_subdir)
return script_paths
-_presets = os.path.join(_scripts[0], "presets") # FIXME - multiple paths
+_presets = _os.path.join(_scripts[0], "presets") # FIXME - multiple paths
def preset_paths(subdir):
@@ -115,4 +127,4 @@
Returns a list of paths for a spesific preset.
'''
- return (os.path.join(_presets, subdir), )
+ return (_os.path.join(_presets, subdir), )
Modified: trunk/blender/source/blender/python/intern/bpy_props.c
===================================================================
--- trunk/blender/source/blender/python/intern/bpy_props.c 2010-01-22 01:30:06 UTC (rev 26177)
+++ trunk/blender/source/blender/python/intern/bpy_props.c 2010-01-22 02:04:25 UTC (rev 26178)
@@ -46,6 +46,10 @@
/* Function that sets RNA, NOTE - self is NULL when called from python, but being abused from C so we can pass the srna allong
* This isnt incorrect since its a python object - but be careful */
+static char BPy_BoolProperty_doc[] =
+".. function:: BoolProperty(name=\"\", description=\"\", default=False, hidden=False)\n"
+"\n"
+" Returns a new boolean property definition..";
PyObject *BPy_BoolProperty(PyObject *self, PyObject *args, PyObject *kw)
{
@@ -79,6 +83,10 @@
}
}
+static char BPy_IntProperty_doc[] =
+".. function:: IntProperty(name=\"\", description=\"\", default=0, min=-sys.maxint, max=sys.maxint, soft_min=-sys.maxint, soft_max=sys.maxint, step=1, hidden=False)\n"
+"\n"
+" Returns a new int property definition.";
PyObject *BPy_IntProperty(PyObject *self, PyObject *args, PyObject *kw)
{
StructRNA *srna;
@@ -113,6 +121,10 @@
}
}
+static char BPy_FloatProperty_doc[] =
+".. function:: FloatProperty(name=\"\", description=\"\", default=0.0, min=sys.float_info.min, max=sys.float_info.max, soft_min=sys.float_info.min, soft_max=sys.float_info.max, step=3, precision=2, hidden=False)\n"
+"\n"
+" Returns a new float property definition.";
PyObject *BPy_FloatProperty(PyObject *self, PyObject *args, PyObject *kw)
{
StructRNA *srna;
@@ -147,6 +159,10 @@
}
}
+static char BPy_FloatVectorProperty_doc[] =
+".. function:: FloatVectorProperty(name=\"\", description=\"\", default=(0.0, 0.0, 0.0), min=sys.float_info.min, max=sys.float_info.max, soft_min=sys.float_info.min, soft_max=sys.float_info.max, step=3, precision=2, hidden=False, size=3)\n"
+"\n"
+" Returns a new vector float property definition.";
PyObject *BPy_FloatVectorProperty(PyObject *self, PyObject *args, PyObject *kw)
{
StructRNA *srna;
@@ -213,6 +229,10 @@
}
}
+static char BPy_StringProperty_doc[] =
+".. function:: StringProperty(name=\"\", description=\"\", default=\"\", maxlen=0, hidden=False)\n"
+"\n"
+" Returns a new string property definition.";
PyObject *BPy_StringProperty(PyObject *self, PyObject *args, PyObject *kw)
{
StructRNA *srna;
@@ -291,6 +311,13 @@
return items;
}
+static char BPy_EnumProperty_doc[] =
+".. function:: EnumProperty(items, name=\"\", description=\"\", default=\"\", hidden=False)\n"
+"\n"
+" Returns a new enumerator property definition.\n"
+"\n"
+" :arg items: The items that make up this enumerator.\n"
+" :type items: sequence of string triplets";
PyObject *BPy_EnumProperty(PyObject *self, PyObject *args, PyObject *kw)
{
StructRNA *srna;
@@ -349,6 +376,13 @@
return srna;
}
+static char BPy_PointerProperty_doc[] =
+".. function:: PointerProperty(items, type=\"\", description=\"\", default=\"\", hidden=False)\n"
+"\n"
+" Returns a new pointer property definition.\n"
+"\n"
+" :arg type: Dynamic type from :mod:`bpy.types`.\n"
+" :type type: class";
PyObject *BPy_PointerProperty(PyObject *self, PyObject *args, PyObject *kw)
{
StructRNA *srna;
@@ -388,6 +422,13 @@
return NULL;
}
+static char BPy_CollectionProperty_doc[] =
+".. function:: CollectionProperty(items, type=\"\", description=\"\", default=\"\", hidden=False)\n"
+"\n"
+" Returns a new collection property definition.\n"
+"\n"
+" :arg type: Dynamic type from :mod:`bpy.types`.\n"
+" :type type: class";
PyObject *BPy_CollectionProperty(PyObject *self, PyObject *args, PyObject *kw)
{
StructRNA *srna;
@@ -428,21 +469,22 @@
}
static struct PyMethodDef props_methods[] = {
- {"BoolProperty", (PyCFunction)BPy_BoolProperty, METH_VARARGS|METH_KEYWORDS, ""},
- {"IntProperty", (PyCFunction)BPy_IntProperty, METH_VARARGS|METH_KEYWORDS, ""},
- {"FloatProperty", (PyCFunction)BPy_FloatProperty, METH_VARARGS|METH_KEYWORDS, ""},
- {"FloatVectorProperty", (PyCFunction)BPy_FloatVectorProperty, METH_VARARGS|METH_KEYWORDS, ""},
- {"StringProperty", (PyCFunction)BPy_StringProperty, METH_VARARGS|METH_KEYWORDS, ""},
- {"EnumProperty", (PyCFunction)BPy_EnumProperty, METH_VARARGS|METH_KEYWORDS, ""},
- {"PointerProperty", (PyCFunction)BPy_PointerProperty, METH_VARARGS|METH_KEYWORDS, ""},
- {"CollectionProperty", (PyCFunction)BPy_CollectionProperty, METH_VARARGS|METH_KEYWORDS, ""},
+ {"BoolProperty", (PyCFunction)BPy_BoolProperty, METH_VARARGS|METH_KEYWORDS, BPy_BoolProperty_doc},
+ {"IntProperty", (PyCFunction)BPy_IntProperty, METH_VARARGS|METH_KEYWORDS, BPy_IntProperty_doc},
+ {"FloatProperty", (PyCFunction)BPy_FloatProperty, METH_VARARGS|METH_KEYWORDS, BPy_FloatProperty_doc},
+ {"FloatVectorProperty", (PyCFunction)BPy_FloatVectorProperty, METH_VARARGS|METH_KEYWORDS, BPy_FloatVectorProperty_doc},
+ {"StringProperty", (PyCFunction)BPy_StringProperty, METH_VARARGS|METH_KEYWORDS, BPy_StringProperty_doc},
+ {"EnumProperty", (PyCFunction)BPy_EnumProperty, METH_VARARGS|METH_KEYWORDS, BPy_EnumProperty_doc},
+ {"PointerProperty", (PyCFunction)BPy_PointerProperty, METH_VARARGS|METH_KEYWORDS, BPy_PointerProperty_doc},
+ {"CollectionProperty", (PyCFunction)BPy_CollectionProperty, METH_VARARGS|METH_KEYWORDS, BPy_CollectionProperty_doc},
{NULL, NULL, 0, NULL}
};
static struct PyModuleDef props_module = {
PyModuleDef_HEAD_INIT,
"bpy.props",
- "",
+ "This module defines properties to extend blenders internal data, the result of these functions"
+ " is used to assign properties to classes registered with blender and can't be used directly.",
-1,/* multiple "initialization" just copies the module dict. */
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list