[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [44710] trunk/blender/doc/python_api: == Python API docs ==
Luca Bonavita
mindrones at gmail.com
Wed Mar 7 18:36:40 CET 2012
Revision: 44710
http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=44710
Author: mindrones
Date: 2012-03-07 17:36:38 +0000 (Wed, 07 Mar 2012)
Log Message:
-----------
== Python API docs ==
(sphinx_doc_gen.py)
- file reorganization to use more functions (easier to read)
- adapting to work after a recent commit that made some of the members of bpy.app.*
output bytes instead of strings (see [#30154])
- a couple of new command line optionsto avoid editing the script:
-T: let you choose the sphinx theme: the theme dir get copied in the destination dir
-b: choose if we want the bpy module page or not
Current command line arguments optional arguments:
-h, --help show this help message and exit
-o OUTPUT_DIR, --output OUTPUT_DIR
Path of the API docs (default=<script dir>)
-T SPHINX_THEME, --sphinxtheme SPHINX_THEME
Sphinx theme (default='default')
-f, --fullrebuild Rewrite all rst files in sphinx-in/ (default=False)
-t, --testdump Dumps a small part of the API (default=False)
-b, --bpy Write the rst file of the bpy module (default=False)
(rst/info_best_practice.rst)
- fixed a typo
Modified Paths:
--------------
trunk/blender/doc/python_api/rst/info_best_practice.rst
trunk/blender/doc/python_api/sphinx_doc_gen.py
Modified: trunk/blender/doc/python_api/rst/info_best_practice.rst
===================================================================
--- trunk/blender/doc/python_api/rst/info_best_practice.rst 2012-03-07 17:18:57 UTC (rev 44709)
+++ trunk/blender/doc/python_api/rst/info_best_practice.rst 2012-03-07 17:36:38 UTC (rev 44710)
@@ -264,7 +264,7 @@
Use try/except Sparingly
------------------------
-The **try** statement useful to save time writing error checking code.
+The **try** statement is useful to save time writing error checking code.
However **try** is significantly slower then an **if** since an exception has to be set each time, so avoid using **try** in areas of your code that execute in a loop and runs many times.
Modified: trunk/blender/doc/python_api/sphinx_doc_gen.py
===================================================================
--- trunk/blender/doc/python_api/sphinx_doc_gen.py 2012-03-07 17:18:57 UTC (rev 44709)
+++ trunk/blender/doc/python_api/sphinx_doc_gen.py 2012-03-07 17:36:38 UTC (rev 44710)
@@ -14,7 +14,7 @@
# along with this program; if not, write to the Free Software Foundation,
# Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
- # Contributor(s): Campbell Barton
+ # Contributor(s): Campbell Barton, Luca Bonavita
#
# #**** END GPL LICENSE BLOCK #****
@@ -77,12 +77,12 @@
from platform import platform
PLATFORM = platform().split('-')[0].lower() # 'linux', 'darwin', 'windows'
+SCRIPT_DIR = os.path.dirname(__file__)
def handle_args():
'''
- Get the args passed to Blender after "--", ignored by Blender
+ Parse the args passed to Blender after "--", ignored by Blender
'''
-
import argparse
# When --help is given, print the usage text
@@ -91,81 +91,104 @@
usage=SCRIPT_HELP_MSG
)
+ # optional arguments
parser.add_argument("-o", "--output",
dest="output_dir",
type=str,
- help="Path of the API docs (optional)",
+ default=SCRIPT_DIR,
+ help="Path of the API docs (default=<script dir>)",
required=False)
+ parser.add_argument("-T", "--sphinxtheme",
+ dest="sphinx_theme",
+ type=str,
+ default='default',
+ help="Sphinx theme (default='default')",
+ required=False)
+
parser.add_argument("-f", "--fullrebuild",
dest="full_rebuild",
default=False,
action='store_true',
- help="Rewrite all rst files in sphinx-in/ (optional)",
+ help="Rewrite all rst files in sphinx-in/ (default=False)",
required=False)
- parser.add_argument("-t", "--testbuild",
- dest="test_build",
+ parser.add_argument("-t", "--testdump",
+ dest="test_dump",
default=False,
action='store_true',
- help="Build only a small part of the API (optional)",
+ help="Dumps a small part of the API (default=False)",
required=False)
+ parser.add_argument("-b", "--bpy",
+ dest="bpy",
+ default=False,
+ action='store_true',
+ help="Write the rst file of the bpy module (default=False)",
+ required=False)
+
+
+ # parse only the args passed after '--'
argv = []
if "--" in sys.argv:
argv = sys.argv[sys.argv.index("--") + 1:] # get all args after "--"
return parser.parse_args(argv)
-SCRIPT_ARGS = handle_args()
-SCRIPT_DIR = os.path.dirname(__file__)
+ARGS = handle_args()
+
+# ----------------------------------BPY-----------------------------------------
+
+"""
# for quick rebuilds
-"""
rm -rf /b/doc/python_api/sphinx-* && \
./blender.bin --background -noaudio --factory-startup --python doc/python_api/sphinx_doc_gen.py && \
sphinx-build doc/python_api/sphinx-in doc/python_api/sphinx-out
"""
-# Switch for quick testing
-if not SCRIPT_ARGS.test_build:
+# Switch for quick testing so doc-builds don't take so long
+if not ARGS.test_dump:
# full build
+ FILTER_BPY_OPS = None
+ FILTER_BPY_TYPES = None
EXCLUDE_INFO_DOCS = False
EXCLUDE_MODULES = ()
- FILTER_BPY_TYPES = None
- FILTER_BPY_OPS = None
else:
+ FILTER_BPY_OPS = ("import.scene", ) # allow
+ FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID") # allow
EXCLUDE_INFO_DOCS = True
- # for testing so doc-builds dont take so long.
EXCLUDE_MODULES = (
- "bpy.context",
+ "aud",
+ "bge",
+ "bge.constraints",
+ "bge.events",
+ "bge.logic",
+ "bge.render",
+ "bge.texture",
+ "bge.types",
+ "bgl",
+ "blf",
+ #"bmesh",
+ #"bmesh.types",
+ #"bmesh.utils",
"bpy.app",
"bpy.app.handlers",
+ "bpy.context",
+ "bpy.data",
+ "bpy.ops", # supports filtering
"bpy.path",
- "bpy.data",
"bpy.props",
+ "bpy.types", # supports filtering
"bpy.utils",
- "bpy.context",
- "bpy.types", # supports filtering
- "bpy.ops", # supports filtering
"bpy_extras",
- "bge",
- "aud",
- "bgl",
- "blf",
"gpu",
"mathutils",
"mathutils.geometry",
"mathutils.noise",
- #"bmesh",
- #"bmesh.types",
- #"bmesh.utils",
)
- FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID") # allow
- FILTER_BPY_OPS = ("import.scene", ) # allow
-
try:
__import__("aud")
except ImportError:
@@ -175,6 +198,9 @@
# examples
EXAMPLES_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "examples"))
EXAMPLE_SET = set()
+for f in os.listdir(EXAMPLES_DIR):
+ if f.endswith(".py"):
+ EXAMPLE_SET.add(os.path.splitext(f)[0])
EXAMPLE_SET_USED = set()
#rst files dir
@@ -186,19 +212,62 @@
("info_quickstart.rst", "Blender/Python Quickstart: new to blender/scripting and want to get your feet wet?"),
("info_overview.rst", "Blender/Python API Overview: a more complete explanation of python integration"),
("info_best_practice.rst", "Best Practice: Conventions to follow for writing good scripts"),
- ("info_tips_and_tricks.rst", "Tips and Tricks: Hints to help you while writeing scripts for blender"),
+ ("info_tips_and_tricks.rst", "Tips and Tricks: Hints to help you while writing scripts for blender"),
("info_gotcha.rst", "Gotcha's: some of the problems you may come up against when writing scripts"),
)
# only support for properties atm.
RNA_BLACKLIST = {
- # messes up PDF!, really a bug but for now just workaround.
- "UserPreferencesSystem": {"language", },
+ # XXX messes up PDF!, really a bug but for now just workaround.
+ "UserPreferencesSystem": {"language", }
}
-# -----------------------------------------------------------------------------
+
+# -------------------------------SPHINX-----------------------------------------
+
+def sphinx_dirs():
+ '''
+ Directories where we write rst files for Sphinx
+ '''
+ if not os.path.exists(ARGS.output_dir):
+ os.mkdir(ARGS.output_dir)
+
+ sphinx_in = os.path.join(ARGS.output_dir, "sphinx-in")
+ sphinx_out = os.path.join(ARGS.output_dir, "sphinx-out")
+ sphinx_in_tmp = sphinx_in + "-tmp"
+ if not os.path.exists(sphinx_in):
+ os.mkdir(sphinx_in)
+
+ return sphinx_in, sphinx_in_tmp, sphinx_out
+
+SPHINX_THEME = ARGS.sphinx_theme
+SPHINX_IN, SPHINX_IN_TMP, SPHINX_OUT = sphinx_dirs()
+if SPHINX_THEME != 'default':
+ SPHINX_THEME_PATH = os.path.join(ARGS.output_dir, SPHINX_THEME)
+SPHINX_THEME_PATH_SVN = os.path.join(SCRIPT_DIR, SPHINX_THEME)
+
# configure compile time options
+# -------------------------------BLENDER----------------------------------------
+
+'''
+blender version
+'''
+version_strings = [str(v) for v in bpy.app.version]
+
+BLENDER_VERSION_DOTS = ".".join(version_strings) # '2.62.1'
+if bpy.app.build_revision != b"Unknown":
+ # converting bytes to strings, due to #30154
+ BLENDER_VERSION_DOTS += " r" + str(bpy.app.build_revision, 'utf_8') # '2.62.1 r44584'
+
+BLENDER_VERSION_PDF = "_".join(version_strings) # '2_62_1'
+if bpy.app.version_cycle == "release":
+ BLENDER_VERSION_PDF = "%s%s_release" % ("_".join(version_strings[:2]),
+ bpy.app.version_char) # '2_62_release'
+
+
+# --------------------------------API DUMP--------------------------------------
+
# lame, python wont give some access
ClassMethodDescriptorType = type(dict.__dict__['fromkeys'])
MethodDescriptorType = type(dict.get)
@@ -440,10 +509,10 @@
fw(ident + " (readonly)\n\n")
-def pymodule2sphinx(BASEPATH, module_name, module, title):
+def pymodule2sphinx(basepath, module_name, module, title):
import types
attribute_set = set()
- filepath = os.path.join(BASEPATH, module_name + ".rst")
+ filepath = os.path.join(basepath, module_name + ".rst")
module_all = getattr(module, "__all__", None)
module_dir = sorted(dir(module))
@@ -491,7 +560,7 @@
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)
+ pymodule2sphinx(basepath, submod_name_full, submod, "%s submodule" % module_name)
del submod_ls
# done writing submodules!
@@ -628,10 +697,10 @@
file.close()
-def pycontext2sphinx(BASEPATH):
+def pycontext2sphinx(basepath):
# Only use once. very irregular
- filepath = os.path.join(BASEPATH, "bpy.context.rst")
+ filepath = os.path.join(basepath, "bpy.context.rst")
file = open(filepath, "w", encoding="utf-8")
fw = file.write
fw("Context Access (bpy.context)\n")
@@ -770,7 +839,7 @@
return ""
-def pyrna2sphinx(BASEPATH):
+def pyrna2sphinx(basepath):
""" bpy.types and bpy.ops
"""
structs, funcs, ops, props = rna_info.BuildRNAInfo()
@@ -822,7 +891,7 @@
#if not struct.identifier == "Object":
# return
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list