Cr8-xyz/blender
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

== Python API docs ==

Browse Source 
(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
This commit is contained in:
Luca Bonavita
2012-03-07 17:36:38 +00:00
parent 8a06ee3d42
commit 4aadffa80e
2 changed files with 346 additions and 300 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/python_api/rst/info_best_practice.rst
View File

@@ -264,7 +264,7 @@ if your unsure whether the text is upper or lower case use lower or upper string
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.

634
doc/python_api/sphinx_doc_gen.py
View File

@@ -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 @@ import shutil
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 @@ def handle_args():
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__)
# for quick rebuilds
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",
"bpy.app",
"bpy.app.handlers",
"bpy.path",
"bpy.data",
"bpy.props",
"bpy.utils",
"bpy.context",
"bpy.types", # supports filtering
"bpy.ops", # supports filtering
"bpy_extras",
"bge",
"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.props",
"bpy.types", # supports filtering
"bpy.utils",
"bpy_extras",
"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 @@ except ImportError:
# 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_DOCS = (
("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 @@ def pyprop2sphinx(ident, fw, identifier, py_prop):
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 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
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 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
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 @@ def pyrna_enum2sphinx(prop, use_empty_descriptions=False):
return ""
def pyrna2sphinx(BASEPATH):
def pyrna2sphinx(basepath):
""" bpy.types and bpy.ops
"""
structs, funcs, ops, props = rna_info.BuildRNAInfo()
@@ -822,7 +891,7 @@ def pyrna2sphinx(BASEPATH):
#if not struct.identifier == "Object":
# return
filepath = os.path.join(BASEPATH, "bpy.types.%s.rst" % struct.identifier)
filepath = os.path.join(basepath, "bpy.types.%s.rst" % struct.identifier)
file = open(filepath, "w", encoding="utf-8")
fw = file.write
@@ -1045,7 +1114,7 @@ def pyrna2sphinx(BASEPATH):
write_struct(struct)
def fake_bpy_type(class_value, class_name, descr_str, use_subclasses=True):
filepath = os.path.join(BASEPATH, "bpy.types.%s.rst" % class_name)
filepath = os.path.join(basepath, "bpy.types.%s.rst" % class_name)
file = open(filepath, "w", encoding="utf-8")
fw = file.write
@@ -1096,7 +1165,7 @@ def pyrna2sphinx(BASEPATH):
del op
for op_module_name, ops_mod in op_modules.items():
filepath = os.path.join(BASEPATH, "bpy.ops.%s.rst" % op_module_name)
filepath = os.path.join(basepath, "bpy.ops.%s.rst" % op_module_name)
file = open(filepath, "w", encoding="utf-8")
fw = file.write
@@ -1134,7 +1203,10 @@ def pyrna2sphinx(BASEPATH):
else:
url_base = API_BASEURL
fw(" :file: `%s <%s/%s>`_:%d\n\n" % (location[0], url_base, location[0], location[1]))
fw(" :file: `%s <%s/%s>`_:%d\n\n" % (location[0],
url_base,
location[0],
location[1]))
file.close()
@@ -1142,53 +1214,42 @@ def pyrna2sphinx(BASEPATH):
write_ops()
def rna2sphinx(BASEPATH):
try:
os.mkdir(BASEPATH)
except:
pass
# conf.py - empty for now
filepath = os.path.join(BASEPATH, "conf.py")
def write_sphinx_conf_py(basepath):
'''
Write sphinx's conf.py
'''
filepath = os.path.join(basepath, "conf.py")
file = open(filepath, "w", encoding="utf-8")
fw = file.write
version_string = ".".join(str(v) for v in bpy.app.version)
if bpy.app.build_revision != "Unknown":
version_string = version_string + " r" + bpy.app.build_revision
version_string_fp = "_".join(str(v) for v in bpy.app.version)
if bpy.app.version_cycle == "release":
version_string_pdf = "%s%s_release" % ("_".join(str(v) for v in bpy.app.version[:2]), bpy.app.version_char)
else:
version_string_pdf = version_string_fp
fw("project = 'Blender'\n")
# fw("master_doc = 'index'\n")
fw("copyright = u'Blender Foundation'\n")
fw("version = '%s - API'\n" % version_string)
fw("release = '%s - API'\n" % version_string)
fw("version = '%s - API'\n" % BLENDER_VERSION_DOTS)
fw("release = '%s - API'\n" % BLENDER_VERSION_DOTS)
# until we get a theme for 'Naiad'
if 0:
fw("html_theme = 'blender-org'\n")
fw("html_theme_path = ['../']\n")
if SPHINX_THEME != 'default':
fw("html_theme = '%s'\n" % SPHINX_THEME) # 'blender-org', 'naiad'
fw("html_theme_path = ['../']\n") # XXX?
# copied with the theme, exclude else we get an error [#28873]
fw("html_favicon = 'favicon.ico'\n")
fw("html_favicon = 'favicon.ico'\n") # in <theme/>static/
# not helpful since the source us generated, adds to upload size.
# not helpful since the source is generated, adds to upload size.
fw("html_copy_source = False\n")
fw("\n")
# needed for latex, pdf gen
fw("latex_documents = [ ('contents', 'contents.tex', 'Blender Index', 'Blender Foundation', 'manual'), ]\n")
fw("latex_paper_size = 'a4paper'\n")
file.close()
# main page needed for sphinx (index.html)
filepath = os.path.join(BASEPATH, "contents.rst")
def write_rst_contents(basepath):
'''
Write the rst file of the main page, needed for sphinx (index.html)
'''
filepath = os.path.join(basepath, "contents.rst")
file = open(filepath, "w", encoding="utf-8")
fw = file.write
@@ -1196,11 +1257,11 @@ def rna2sphinx(BASEPATH):
fw(" Blender Documentation contents\n")
fw("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n")
fw("\n")
fw("Welcome, this document is an API reference for Blender %s. built %s.\n" % (version_string, bpy.app.build_date))
fw("Welcome, this document is an API reference for Blender %s. built %s.\n" % (BLENDER_VERSION_DOTS, str(bpy.app.build_date, 'utf_8')))
fw("\n")
# fw("`A PDF version of this document is also available <blender_python_reference_%s.pdf>`_\n" % version_string_pdf)
fw("`A compressed ZIP file of this site is available <blender_python_reference_%s.zip>`_\n" % version_string_pdf)
# fw("`A PDF version of this document is also available <blender_python_reference_%s.pdf>`_\n" % BLENDER_VERSION_PDF)
fw("`A compressed ZIP file of this site is available <blender_python_reference_%s.zip>`_\n" % BLENDER_VERSION_PDF)
fw("\n")
@@ -1222,28 +1283,25 @@ def rna2sphinx(BASEPATH):
fw("\n")
fw(".. toctree::\n")
fw(" :maxdepth: 1\n\n")
if "bpy.context" not in EXCLUDE_MODULES:
fw(" bpy.context.rst\n\n") # note: not actually a module
if "bpy.data" not in EXCLUDE_MODULES:
fw(" bpy.data.rst\n\n") # note: not actually a module
if "bpy.ops" not in EXCLUDE_MODULES:
fw(" bpy.ops.rst\n\n")
if "bpy.types" not in EXCLUDE_MODULES:
fw(" bpy.types.rst\n\n")
# py modules
if "bpy.utils" not in EXCLUDE_MODULES:
fw(" bpy.utils.rst\n\n")
if "bpy.path" not in EXCLUDE_MODULES:
fw(" bpy.path.rst\n\n")
if "bpy.app" not in EXCLUDE_MODULES:
fw(" bpy.app.rst\n\n")
if "bpy.app.handlers" not in EXCLUDE_MODULES:
fw(" bpy.app.handlers.rst\n\n")
app_modules = [
"bpy.context", # note: not actually a module
"bpy.data", # note: not actually a module
"bpy.ops",
"bpy.types",
# C modules
if "bpy.props" not in EXCLUDE_MODULES:
fw(" bpy.props.rst\n\n")
# py modules
"bpy.utils",
"bpy.path",
"bpy.app",
"bpy.app.handlers",
# C modules
"bpy.props"
]
for mod in app_modules:
if mod not in EXCLUDE_MODULES:
fw(" %s\n\n" % mod)
fw("==================\n")
fw("Standalone Modules\n")
@@ -1252,31 +1310,17 @@ def rna2sphinx(BASEPATH):
fw(".. toctree::\n")
fw(" :maxdepth: 1\n\n")
# mathutils
if "mathutils" not in EXCLUDE_MODULES:
fw(" mathutils.rst\n\n")
if "mathutils.geometry" not in EXCLUDE_MODULES:
fw(" mathutils.geometry.rst\n\n")
if "mathutils.noise" not in EXCLUDE_MODULES:
fw(" mathutils.noise.rst\n\n")
# misc
if "bgl" not in EXCLUDE_MODULES:
fw(" bgl.rst\n\n")
if "blf" not in EXCLUDE_MODULES:
fw(" blf.rst\n\n")
if "gpu" not in EXCLUDE_MODULES:
fw(" gpu.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")
# bmesh
if "bmesh" not in EXCLUDE_MODULES:
fw(" bmesh.rst\n\n")
if "bmesh.types" not in EXCLUDE_MODULES:
fw(" bmesh.types.rst\n\n")
if "bmesh.utils" not in EXCLUDE_MODULES:
fw(" bmesh.utils.rst\n\n")
standalone_modules = [
# mathutils
"mathutils", "mathutils.geometry", "mathutils.noise",
# misc
"bgl", "blf", "gpu", "aud", "bpy_extras",
# bmesh
"bmesh", "bmesh.types", "bmesh.utils"
]
for mod in standalone_modules:
if mod not in EXCLUDE_MODULES:
fw(" %s\n\n" % mod)
# game engine
if "bge" not in EXCLUDE_MODULES:
@@ -1319,9 +1363,48 @@ def rna2sphinx(BASEPATH):
file.close()
# internal modules
def write_rst_bpy(basepath):
'''
Write rst file of bpy module (disabled by default)
'''
if ARGS.bpy:
filepath = os.path.join(basepath, "bpy.rst")
file = open(filepath, "w", encoding="utf-8")
fw = file.write
fw("\n")
title = ":mod:`bpy` --- Blender Python Module"
write_title(fw, title, "=")
fw(".. module:: bpy.types\n\n")
file.close()
def write_rst_types_index(basepath):
'''
Write the rst file of bpy.types module (index)
'''
if "bpy.types" not in EXCLUDE_MODULES:
filepath = os.path.join(basepath, "bpy.types.rst")
file = open(filepath, "w", encoding="utf-8")
fw = file.write
fw("Types (bpy.types)\n")
fw("=================\n\n")
fw(".. toctree::\n")
fw(" :glob:\n\n")
fw(" bpy.types.*\n\n")
file.close()
def write_rst_ops_index(basepath):
'''
Write the rst file of bpy.ops module (index)
'''
if "bpy.ops" not in EXCLUDE_MODULES:
filepath = os.path.join(BASEPATH, "bpy.ops.rst")
filepath = os.path.join(basepath, "bpy.ops.rst")
file = open(filepath, "w", encoding="utf-8")
fw = file.write
fw("Operators (bpy.ops)\n")
@@ -1332,21 +1415,15 @@ def rna2sphinx(BASEPATH):
fw(" bpy.ops.*\n\n")
file.close()
if "bpy.types" not in EXCLUDE_MODULES:
filepath = os.path.join(BASEPATH, "bpy.types.rst")
file = open(filepath, "w", encoding="utf-8")
fw = file.write
fw("Types (bpy.types)\n")
fw("=================\n\n")
fw(".. toctree::\n")
fw(" :glob:\n\n")
fw(" bpy.types.*\n\n")
file.close()
def write_rst_data(basepath):
'''
Write the rst file of bpy.data module
'''
if "bpy.data" not in EXCLUDE_MODULES:
# not actually a module, only write this file so we
# can reference in the TOC
filepath = os.path.join(BASEPATH, "bpy.data.rst")
filepath = os.path.join(basepath, "bpy.data.rst")
file = open(filepath, "w", encoding="utf-8")
fw = file.write
fw("Data Access (bpy.data)\n")
@@ -1364,184 +1441,152 @@ def rna2sphinx(BASEPATH):
fw(".. literalinclude:: ../examples/bpy.data.py\n")
file.close()
EXAMPLE_SET_USED.add("bpy.data")
EXAMPLE_SET_USED.add("bpy.data")
module = None
def write_rst_importable_modules(basepath):
'''
Write the rst files of importable modules
'''
importable_modules = {
# python_modules
"bpy.path" : "Path Utilities",
"bpy.utils" : "Utilities",
"bpy_extras" : "Extra Utilities",
# C_modules
"aud" : "Audio System",
"blf" : "Font Drawing",
"bmesh" : "BMesh Module",
"bmesh.types" : "BMesh Types",
"bmesh.utils" : "BMesh Utilities",
"bpy.app" : "Application Data",
"bpy.app.handlers" : "Application Handlers",
"bpy.props" : "Property Definitions",
"mathutils" : "Math Types & Utilities",
"mathutils.geometry": "Geometry Utilities",
"mathutils.noise" : "Noise Utilities",
}
for mod_name, mod_descr in importable_modules.items():
if mod_name not in EXCLUDE_MODULES:
module = __import__(mod_name,
fromlist=[mod_name.rsplit(".", 1)[-1]])
pymodule2sphinx(basepath, mod_name, module, mod_descr)
def copy_handwritten_rsts(basepath):
# info docs
if not EXCLUDE_INFO_DOCS:
for info, info_desc in INFO_DOCS:
shutil.copy2(os.path.join(RST_DIR, info), basepath)
# TODO put this docs in blender's code and use import as per modules above
handwritten_modules = [
"bge.types",
"bge.logic",
"bge.render",
"bge.texture",
"bge.events",
"bge.constraints",
"bgl", # "Blender OpenGl wrapper"
"gpu", # "GPU Shader Module"
]
for mod_name in handwritten_modules:
if mod_name not in EXCLUDE_MODULES:
# copy2 keeps time/date stamps
shutil.copy2(os.path.join(RST_DIR, "%s.rst" % mod_name), basepath)
# changelog
shutil.copy2(os.path.join(RST_DIR, "change_log.rst"), basepath)
def rna2sphinx(basepath):
try:
os.mkdir(basepath)
except:
pass
# sphinx setup
write_sphinx_conf_py(basepath)
# main page
write_rst_contents(basepath)
# context
if "bpy.context" not in EXCLUDE_MODULES:
# one of a kind, context doc (uses ctypes to extract info!)
# doesn't work on mac
if PLATFORM != "darwin":
pycontext2sphinx(BASEPATH)
pycontext2sphinx(basepath)
# python modules
if "bpy.utils" not in EXCLUDE_MODULES:
from bpy import utils as module
pymodule2sphinx(BASEPATH, "bpy.utils", module, "Utilities")
# internal modules
write_rst_bpy(basepath) # bpy, disabled by default
write_rst_types_index(basepath) # bpy.types
write_rst_ops_index(basepath) # bpy.ops
pyrna2sphinx(basepath) # bpy.types.* and bpy.ops.*
write_rst_data(basepath) # bpy.data
write_rst_importable_modules(basepath)
if "bpy.path" not in EXCLUDE_MODULES:
from bpy import path as module
pymodule2sphinx(BASEPATH, "bpy.path", module, "Path Utilities")
# copy the other rsts
copy_handwritten_rsts(basepath)
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")
def align_sphinx_in_to_sphinx_in_tmp():
'''
Move changed files from SPHINX_IN_TMP to SPHINX_IN
'''
import filecmp
if "bpy.app.handlers" not in EXCLUDE_MODULES:
from bpy.app import handlers as module
pymodule2sphinx(BASEPATH, "bpy.app.handlers", module, "Application Handlers")
sphinx_in_files = set(os.listdir(SPHINX_IN))
sphinx_in_tmp_files = set(os.listdir(SPHINX_IN_TMP))
if "bpy.props" not in EXCLUDE_MODULES:
from bpy import props as module
pymodule2sphinx(BASEPATH, "bpy.props", module, "Property Definitions")
# remove deprecated files that have been removed
for f in sorted(sphinx_in_files):
if f not in sphinx_in_tmp_files:
print("\tdeprecated: %s" % f)
os.remove(os.path.join(SPHINX_IN, f))
if "mathutils" not in EXCLUDE_MODULES:
import mathutils as module
pymodule2sphinx(BASEPATH, "mathutils", module, "Math Types & Utilities")
# freshen with new files.
for f in sorted(sphinx_in_tmp_files):
f_from = os.path.join(SPHINX_IN_TMP, f)
f_to = os.path.join(SPHINX_IN, f)
if "mathutils.geometry" not in EXCLUDE_MODULES:
import mathutils.geometry as module
pymodule2sphinx(BASEPATH, "mathutils.geometry", module, "Geometry Utilities")
do_copy = True
if f in sphinx_in_files:
if filecmp.cmp(f_from, f_to):
do_copy = False
if "mathutils.noise" not in EXCLUDE_MODULES:
import mathutils.noise as module
pymodule2sphinx(BASEPATH, "mathutils.noise", module, "Noise Utilities")
if "bmesh" not in EXCLUDE_MODULES:
import bmesh as module
pymodule2sphinx(BASEPATH, "bmesh", module, "BMesh Module")
if "bmesh.types" not in EXCLUDE_MODULES:
import bmesh.types as module
pymodule2sphinx(BASEPATH, "bmesh.types", module, "BMesh Types")
if "bmesh.utils" not in EXCLUDE_MODULES:
import bmesh.utils as module
pymodule2sphinx(BASEPATH, "bmesh.utils", module, "BMesh Utilities")
if "blf" not in EXCLUDE_MODULES:
import blf as module
pymodule2sphinx(BASEPATH, "blf", module, "Font Drawing")
if "bgl" not in EXCLUDE_MODULES:
#import bgl as module
#pymodule2sphinx(BASEPATH, "bgl", module, "Blender OpenGl wrapper")
#del module
shutil.copy2(os.path.join(RST_DIR, "bgl.rst"), BASEPATH)
if "gpu" not in EXCLUDE_MODULES:
#import gpu as module
#pymodule2sphinx(BASEPATH, "gpu", module, "GPU Shader Module")
#del module
shutil.copy2(os.path.join(RST_DIR, "gpu.rst"), BASEPATH)
if "aud" not in EXCLUDE_MODULES:
import aud as module
pymodule2sphinx(BASEPATH, "aud", module, "Audio System")
del module
## game engine
# copy2 keeps time/date stamps
if "bge" not in EXCLUDE_MODULES:
shutil.copy2(os.path.join(RST_DIR, "bge.types.rst"), BASEPATH)
shutil.copy2(os.path.join(RST_DIR, "bge.logic.rst"), BASEPATH)
shutil.copy2(os.path.join(RST_DIR, "bge.render.rst"), BASEPATH)
shutil.copy2(os.path.join(RST_DIR, "bge.texture.rst"), BASEPATH)
shutil.copy2(os.path.join(RST_DIR, "bge.events.rst"), BASEPATH)
shutil.copy2(os.path.join(RST_DIR, "bge.constraints.rst"), BASEPATH)
shutil.copy2(os.path.join(RST_DIR, "change_log.rst"), BASEPATH)
if not EXCLUDE_INFO_DOCS:
for info, info_desc in INFO_DOCS:
shutil.copy2(os.path.join(RST_DIR, info), BASEPATH)
if 0:
filepath = os.path.join(BASEPATH, "bpy.rst")
file = open(filepath, "w", encoding="utf-8")
fw = file.write
fw("\n")
title = ":mod:`bpy` --- Blender Python Module"
write_title(fw, title, "=")
fw(".. module:: bpy.types\n\n")
file.close()
# bpy.types and bpy.ops
pyrna2sphinx(BASEPATH)
file.close()
if do_copy:
print("\tupdating: %s" % f)
shutil.copy(f_from, f_to)
def main():
# output dir
if SCRIPT_ARGS.output_dir:
output_dir = SCRIPT_ARGS.output_dir
if not os.path.exists(SCRIPT_ARGS.output_dir):
os.mkdir(SCRIPT_ARGS.output_dir)
else:
output_dir = SCRIPT_DIR
# sphinx dirs
sphinx_in_dir = os.path.join(output_dir, "sphinx-in")
sphinx_out_dir = os.path.join(output_dir, "sphinx-out")
sphinx_in_tmp_dir = sphinx_in_dir + "-tmp"
if not os.path.exists(sphinx_in_dir):
os.mkdir(sphinx_in_dir)
for f in os.listdir(EXAMPLES_DIR):
if f.endswith(".py"):
EXAMPLE_SET.add(os.path.splitext(f)[0])
# only for full updates
if SCRIPT_ARGS.full_rebuild:
shutil.rmtree(sphinx_in_dir, True)
shutil.rmtree(sphinx_out_dir, True)
# dump the api in rst files
if ARGS.full_rebuild:
# only for full updates
shutil.rmtree(SPHINX_IN, True)
shutil.rmtree(SPHINX_OUT, True)
rna2sphinx(SPHINX_IN_TMP)
shutil.copytree(SPHINX_IN_TMP,
SPHINX_IN,
copy_function=shutil.copy)
else:
# write here, then move
shutil.rmtree(sphinx_in_tmp_dir, True)
shutil.rmtree(SPHINX_IN_TMP, True)
rna2sphinx(SPHINX_IN_TMP)
align_sphinx_in_to_sphinx_in_tmp()
rna2sphinx(sphinx_in_tmp_dir)
if not SCRIPT_ARGS.full_rebuild:
import filecmp
# now move changed files from 'sphinx_in_tmp_dir' --> 'sphinx_in_dir'
file_list_sphinx_in_dir = set(os.listdir(sphinx_in_dir))
file_list_sphinx_in_tmp_dir = set(os.listdir(sphinx_in_tmp_dir))
# remove deprecated files that have been removed.
for f in sorted(file_list_sphinx_in_dir):
if f not in file_list_sphinx_in_tmp_dir:
print("\tdeprecated: %s" % f)
os.remove(os.path.join(sphinx_in_dir, f))
# freshen with new files.
for f in sorted(file_list_sphinx_in_tmp_dir):
f_from = os.path.join(sphinx_in_tmp_dir, f)
f_to = os.path.join(sphinx_in_dir, f)
do_copy = True
if f in file_list_sphinx_in_dir:
if filecmp.cmp(f_from, f_to):
do_copy = False
if do_copy:
print("\tupdating: %s" % f)
shutil.copy(f_from, f_to)
'''else:
print("\tkeeping: %s" % f) # eh, not that useful'''
# copy the theme in the output directory
if SPHINX_THEME != 'default' and not os.path.exists(SPHINX_THEME_PATH):
shutil.copytree(SPHINX_THEME_PATH_SVN,
SPHINX_THEME_PATH,
copy_function=shutil.copy)
# report which example files weren't used
EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED
if EXAMPLE_SET_UNUSED:
print("\nUnused examples found in '%s'..." % EXAMPLES_DIR)
@@ -1551,5 +1596,6 @@ def main():
sys.exit()
if __name__ == '__main__':
main()