2009-12-25 16:50:53 +01:00
|
|
|
# ***** BEGIN GPL LICENSE BLOCK *****
|
|
|
|
#
|
|
|
|
# This program is free software; you can redistribute it and/or
|
|
|
|
# modify it under the terms of the GNU General Public License
|
|
|
|
# as published by the Free Software Foundation; either version 2
|
|
|
|
# of the License, or (at your option) any later version.
|
|
|
|
#
|
|
|
|
# This program is distributed in the hope that it will be useful,
|
|
|
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
# GNU General Public License for more details.
|
|
|
|
#
|
|
|
|
# You should have received a copy of the GNU General Public License
|
|
|
|
# along with this program; if not, write to the Free Software Foundation,
|
2010-02-12 14:34:04 +01:00
|
|
|
# Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
2009-12-25 16:50:53 +01:00
|
|
|
#
|
2012-03-07 18:36:38 +01:00
|
|
|
# Contributor(s): Campbell Barton, Luca Bonavita
|
2009-12-25 16:50:53 +01:00
|
|
|
#
|
|
|
|
# #**** END GPL LICENSE BLOCK #****
|
|
|
|
|
2011-02-04 10:27:25 +01:00
|
|
|
# <pep8 compliant>
|
|
|
|
|
2012-03-05 15:12:38 +01:00
|
|
|
SCRIPT_HELP_MSG = """
|
2009-12-25 16:50:53 +01:00
|
|
|
|
2012-03-02 15:39:18 +01:00
|
|
|
API dump in RST files
|
|
|
|
---------------------
|
|
|
|
Run this script from blenders root path once you have compiled blender
|
2010-10-13 12:42:33 +02:00
|
|
|
|
2012-03-05 15:12:38 +01:00
|
|
|
./blender.bin -b -noaudio -P doc/python_api/sphinx_doc_gen.py
|
2010-01-28 11:48:17 +01:00
|
|
|
|
2011-06-27 06:50:08 +02:00
|
|
|
This will generate python files in doc/python_api/sphinx-in/
|
|
|
|
providing ./blender.bin is or links to the blender executable
|
2010-01-28 11:48:17 +01:00
|
|
|
|
2012-03-05 15:12:38 +01:00
|
|
|
To choose sphinx-in directory:
|
|
|
|
./blender.bin -b -P doc/python_api/sphinx_doc_gen.py -- -o ../python_api
|
|
|
|
|
|
|
|
For quick builds:
|
2012-03-15 01:12:31 +01:00
|
|
|
./blender.bin -b -P doc/python_api/sphinx_doc_gen.py -- -p
|
2012-03-02 15:39:18 +01:00
|
|
|
|
2012-03-13 07:22:43 +01:00
|
|
|
|
2012-03-02 15:39:18 +01:00
|
|
|
Sphinx: HTML generation
|
|
|
|
-----------------------
|
2012-03-05 15:12:38 +01:00
|
|
|
After you have built doc/python_api/sphinx-in (see above),
|
|
|
|
generate html docs by running:
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2011-05-28 09:47:58 +02:00
|
|
|
cd doc/python_api
|
|
|
|
sphinx-build sphinx-in sphinx-out
|
2010-10-13 12:42:33 +02:00
|
|
|
|
2011-06-27 06:50:08 +02:00
|
|
|
This requires sphinx 1.0.7 to be installed.
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2012-03-13 07:22:43 +01:00
|
|
|
|
2012-03-02 15:39:18 +01:00
|
|
|
Sphinx: PDF generation
|
|
|
|
----------------------
|
2012-03-05 15:12:38 +01:00
|
|
|
After you have built doc/python_api/sphinx-in (see above),
|
|
|
|
generate the pdf doc by running:
|
2010-01-28 11:48:17 +01:00
|
|
|
|
2010-10-13 12:42:33 +02:00
|
|
|
sphinx-build -b latex doc/python_api/sphinx-in doc/python_api/sphinx-out
|
|
|
|
cd doc/python_api/sphinx-out
|
2010-01-28 11:48:17 +01:00
|
|
|
make
|
2012-03-05 15:12:38 +01:00
|
|
|
|
2012-03-02 15:39:18 +01:00
|
|
|
"""
|
2009-12-25 16:50:53 +01:00
|
|
|
|
2012-03-02 15:39:18 +01:00
|
|
|
try:
|
|
|
|
import bpy # blender module
|
|
|
|
except:
|
2012-03-05 15:12:38 +01:00
|
|
|
print("\nERROR: this script must run from inside Blender")
|
|
|
|
print(SCRIPT_HELP_MSG)
|
2011-06-27 06:50:08 +02:00
|
|
|
import sys
|
|
|
|
sys.exit()
|
|
|
|
|
2012-03-02 15:39:18 +01:00
|
|
|
import rna_info # blender module
|
|
|
|
|
|
|
|
# import rpdb2; rpdb2.start_embedded_debugger('test')
|
|
|
|
import os
|
|
|
|
import sys
|
|
|
|
import inspect
|
|
|
|
import shutil
|
2012-03-15 01:12:31 +01:00
|
|
|
import logging
|
2012-03-02 15:39:18 +01:00
|
|
|
|
|
|
|
from platform import platform
|
|
|
|
PLATFORM = platform().split('-')[0].lower() # 'linux', 'darwin', 'windows'
|
|
|
|
|
2012-03-08 19:36:23 +01:00
|
|
|
SCRIPT_DIR = os.path.abspath(os.path.dirname(__file__))
|
2012-03-02 15:39:18 +01:00
|
|
|
|
2012-03-08 06:36:05 +01:00
|
|
|
|
2012-03-05 15:12:38 +01:00
|
|
|
def handle_args():
|
|
|
|
'''
|
2012-03-07 18:36:38 +01:00
|
|
|
Parse the args passed to Blender after "--", ignored by Blender
|
2012-03-05 15:12:38 +01:00
|
|
|
'''
|
|
|
|
import argparse
|
|
|
|
|
|
|
|
# When --help is given, print the usage text
|
|
|
|
parser = argparse.ArgumentParser(
|
2012-03-08 19:36:23 +01:00
|
|
|
formatter_class=argparse.RawTextHelpFormatter,
|
2012-03-05 15:12:38 +01:00
|
|
|
usage=SCRIPT_HELP_MSG
|
|
|
|
)
|
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
# optional arguments
|
|
|
|
parser.add_argument("-p", "--partial",
|
|
|
|
dest="partial",
|
2012-03-05 15:12:38 +01:00
|
|
|
type=str,
|
2012-03-15 01:12:31 +01:00
|
|
|
default="",
|
|
|
|
help="Use a wildcard to only build specific module(s)\n"
|
|
|
|
"Example: --partial bmesh*\n",
|
2012-03-07 18:36:38 +01:00
|
|
|
required=False)
|
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
parser.add_argument("-f", "--fullrebuild",
|
|
|
|
dest="full_rebuild",
|
2012-03-08 19:36:23 +01:00
|
|
|
default=False,
|
|
|
|
action='store_true',
|
2012-03-15 01:12:31 +01:00
|
|
|
help="Rewrite all rst files in sphinx-in/ "
|
|
|
|
"(default=False)",
|
2012-03-08 19:36:23 +01:00
|
|
|
required=False)
|
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
parser.add_argument("-b", "--bpy",
|
|
|
|
dest="bpy",
|
2012-03-08 19:36:23 +01:00
|
|
|
default=False,
|
|
|
|
action='store_true',
|
2012-03-15 01:12:31 +01:00
|
|
|
help="Write the rst file of the bpy module "
|
|
|
|
"(default=False)",
|
|
|
|
required=False)
|
|
|
|
|
|
|
|
parser.add_argument("-o", "--output",
|
|
|
|
dest="output_dir",
|
|
|
|
type=str,
|
|
|
|
default=SCRIPT_DIR,
|
|
|
|
help="Path of the API docs (default=<script dir>)",
|
|
|
|
required=False)
|
|
|
|
|
|
|
|
parser.add_argument("-l", "--bpy-log",
|
|
|
|
dest="bpy_log",
|
|
|
|
default=False,
|
|
|
|
action='store_true',
|
|
|
|
help=
|
|
|
|
"Log the output of the api dump (default=False).\n"
|
|
|
|
"If given, save logs in OUTPUT_DIR/.bpy.log",
|
2012-03-08 19:36:23 +01:00
|
|
|
required=False)
|
|
|
|
|
|
|
|
parser.add_argument("-T", "--sphinx-theme",
|
2012-03-07 18:36:38 +01:00
|
|
|
dest="sphinx_theme",
|
|
|
|
type=str,
|
|
|
|
default='default',
|
2012-03-08 19:36:23 +01:00
|
|
|
help=
|
|
|
|
# see SPHINX_THEMES below
|
|
|
|
"Sphinx theme (default='default')\n"
|
|
|
|
"Available themes\n"
|
|
|
|
"----------------\n"
|
|
|
|
"(Blender Foundation) blender-org\n" # naiad
|
|
|
|
"(Sphinx) agogo, basic, epub, haiku, nature, "
|
|
|
|
"scrolls, sphinxdoc, traditional\n",
|
|
|
|
# choices=['naiad', 'blender-org'] + # bf
|
|
|
|
# ['agogo', 'basic', 'epub',
|
|
|
|
# 'haiku', 'nature', 'scrolls',
|
|
|
|
# 'sphinxdoc', 'traditional'], # sphinx
|
2012-03-05 15:12:38 +01:00
|
|
|
required=False)
|
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
parser.add_argument("-N", "--sphinx-named-output",
|
|
|
|
dest="sphinx_named_output",
|
2012-03-05 15:12:38 +01:00
|
|
|
default=False,
|
|
|
|
action='store_true',
|
2012-03-15 01:12:31 +01:00
|
|
|
help="Add the theme name to the html dir name.\n"
|
|
|
|
"Example: \"sphinx-out_haiku\" (default=False)",
|
2012-03-05 15:12:38 +01:00
|
|
|
required=False)
|
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
parser.add_argument("-B", "--sphinx-build",
|
|
|
|
dest="sphinx_build",
|
|
|
|
default=False,
|
|
|
|
action='store_true',
|
|
|
|
help="Build the html docs by running:\n"
|
|
|
|
"sphinx-build SPHINX_IN SPHINX_OUT\n"
|
|
|
|
"(default=False; does not depend on -P)",
|
2012-03-05 15:12:38 +01:00
|
|
|
required=False)
|
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
parser.add_argument("-P", "--sphinx-build-pdf",
|
|
|
|
dest="sphinx_build_pdf",
|
|
|
|
default=False,
|
|
|
|
action='store_true',
|
|
|
|
help="Build the pdf by running:\n"
|
|
|
|
"sphinx-build -b latex SPHINX_IN SPHINX_OUT_PDF\n"
|
|
|
|
"(default=False; does not depend on -B)",
|
|
|
|
required=False)
|
|
|
|
|
|
|
|
parser.add_argument("-R", "--pack-reference",
|
|
|
|
dest="pack_reference",
|
|
|
|
default=False,
|
|
|
|
action='store_true',
|
|
|
|
help="Pack all necessary files in the deployed dir.\n"
|
|
|
|
"(default=False; use with -B and -P)",
|
|
|
|
required=False)
|
|
|
|
|
|
|
|
parser.add_argument("-L", "--sphinx-log",
|
|
|
|
dest="sphinx_log",
|
2012-03-07 18:36:38 +01:00
|
|
|
default=False,
|
|
|
|
action='store_true',
|
2012-03-15 01:12:31 +01:00
|
|
|
help=
|
|
|
|
"Log warnings and errors (default=False).\n"
|
|
|
|
"If given, eventually save logs in:\n"
|
|
|
|
"* OUTPUT_DIR/.sphinx-build.log\n"
|
|
|
|
"* OUTPUT_DIR/.sphinx-build_pdf.log\n"
|
|
|
|
"* OUTPUT_DIR/.latex_make.log",
|
|
|
|
# see SPHINX_BUILD_LOG
|
2012-03-07 18:36:38 +01:00
|
|
|
required=False)
|
|
|
|
|
|
|
|
# parse only the args passed after '--'
|
2012-03-05 15:12:38 +01:00
|
|
|
argv = []
|
|
|
|
if "--" in sys.argv:
|
|
|
|
argv = sys.argv[sys.argv.index("--") + 1:] # get all args after "--"
|
|
|
|
|
|
|
|
return parser.parse_args(argv)
|
|
|
|
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
ARGS = handle_args()
|
|
|
|
|
|
|
|
# ----------------------------------BPY-----------------------------------------
|
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
BPY_LOGGER = logging.getLogger('bpy')
|
|
|
|
BPY_LOGGER.setLevel(logging.DEBUG)
|
|
|
|
|
|
|
|
if ARGS.bpy_log:
|
|
|
|
BPY_LOGFILE = os.path.join(ARGS.output_dir,".bpy.log")
|
|
|
|
bpy_logfilehandler = logging.FileHandler(BPY_LOGFILE, mode="w")
|
|
|
|
bpy_logfilehandler.setLevel(logging.DEBUG)
|
|
|
|
BPY_LOGGER.addHandler(bpy_logfilehandler)
|
|
|
|
|
|
|
|
# using a FileHandler seems to disable the stdout, so we add a StreamHandler
|
|
|
|
bpy_log_stdout_handler = logging.StreamHandler(stream=sys.stdout)
|
|
|
|
bpy_log_stdout_handler.setLevel(logging.DEBUG)
|
|
|
|
BPY_LOGGER.addHandler(bpy_log_stdout_handler)
|
|
|
|
|
2012-03-05 15:12:38 +01:00
|
|
|
"""
|
2012-03-07 18:36:38 +01:00
|
|
|
# for quick rebuilds
|
2012-03-05 15:12:38 +01:00
|
|
|
rm -rf /b/doc/python_api/sphinx-* && \
|
2012-03-15 01:12:31 +01:00
|
|
|
./blender.bin -b -noaudio --factory-startup -P doc/python_api/sphinx_doc_gen.py && \
|
2012-03-05 15:12:38 +01:00
|
|
|
sphinx-build doc/python_api/sphinx-in doc/python_api/sphinx-out
|
2012-03-15 01:12:31 +01:00
|
|
|
|
|
|
|
or
|
|
|
|
|
|
|
|
./blender.bin -b -noaudio --factory-startup -P doc/python_api/sphinx_doc_gen.py -- -f -B
|
2012-03-05 15:12:38 +01:00
|
|
|
"""
|
2011-06-27 06:50:08 +02:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# Switch for quick testing so doc-builds don't take so long
|
2012-03-13 07:22:43 +01:00
|
|
|
if not ARGS.partial:
|
2011-02-16 06:18:10 +01:00
|
|
|
# full build
|
2012-03-07 18:36:38 +01:00
|
|
|
FILTER_BPY_OPS = None
|
|
|
|
FILTER_BPY_TYPES = None
|
2011-08-25 06:25:33 +02:00
|
|
|
EXCLUDE_INFO_DOCS = False
|
2011-02-16 06:18:10 +01:00
|
|
|
EXCLUDE_MODULES = ()
|
|
|
|
|
|
|
|
else:
|
2012-03-13 07:22:43 +01:00
|
|
|
# can manually edit this too:
|
2012-03-07 18:36:38 +01:00
|
|
|
FILTER_BPY_OPS = ("import.scene", ) # allow
|
|
|
|
FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID") # allow
|
2012-02-24 10:53:29 +01:00
|
|
|
EXCLUDE_INFO_DOCS = True
|
2011-02-16 06:18:10 +01:00
|
|
|
EXCLUDE_MODULES = (
|
2012-03-07 18:36:38 +01:00
|
|
|
"aud",
|
|
|
|
"bge",
|
|
|
|
"bge.constraints",
|
|
|
|
"bge.events",
|
|
|
|
"bge.logic",
|
|
|
|
"bge.render",
|
|
|
|
"bge.texture",
|
|
|
|
"bge.types",
|
|
|
|
"bgl",
|
|
|
|
"blf",
|
2012-03-13 07:22:43 +01:00
|
|
|
"bmesh",
|
|
|
|
"bmesh.types",
|
|
|
|
"bmesh.utils",
|
2012-02-24 10:53:29 +01:00
|
|
|
"bpy.app",
|
|
|
|
"bpy.app.handlers",
|
2012-03-07 18:36:38 +01:00
|
|
|
"bpy.context",
|
2011-02-16 06:18:10 +01:00
|
|
|
"bpy.data",
|
2012-03-07 18:36:38 +01:00
|
|
|
"bpy.ops", # supports filtering
|
|
|
|
"bpy.path",
|
2011-03-22 05:28:51 +01:00
|
|
|
"bpy.props",
|
2011-11-04 05:27:46 +01:00
|
|
|
"bpy.types", # supports filtering
|
2012-03-07 18:36:38 +01:00
|
|
|
"bpy.utils",
|
2011-07-01 13:16:42 +02:00
|
|
|
"bpy_extras",
|
2011-10-13 08:59:09 +02:00
|
|
|
"gpu",
|
2011-02-16 06:18:10 +01:00
|
|
|
"mathutils",
|
|
|
|
"mathutils.geometry",
|
2011-12-04 07:55:32 +01:00
|
|
|
"mathutils.noise",
|
2011-02-16 06:18:10 +01:00
|
|
|
)
|
|
|
|
|
2012-03-13 07:22:43 +01:00
|
|
|
# ------
|
|
|
|
# Filter
|
|
|
|
#
|
|
|
|
# TODO, support bpy.ops and bpy.types filtering
|
|
|
|
import fnmatch
|
|
|
|
m = None
|
|
|
|
EXCLUDE_MODULES = tuple([m for m in EXCLUDE_MODULES if not fnmatch.fnmatchcase(m, ARGS.partial)])
|
|
|
|
del m
|
|
|
|
del fnmatch
|
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
BPY_LOGGER.debug("Partial Doc Build, Skipping: %s\n" % "\n ".join(sorted(EXCLUDE_MODULES)))
|
2012-03-13 07:22:43 +01:00
|
|
|
|
|
|
|
#
|
|
|
|
# done filtering
|
|
|
|
# --------------
|
|
|
|
|
2012-03-05 15:12:38 +01:00
|
|
|
try:
|
|
|
|
__import__("aud")
|
|
|
|
except ImportError:
|
2012-03-15 01:12:31 +01:00
|
|
|
BPY_LOGGER.debug("Warning: Built without 'aud' module, docs incomplete...")
|
2012-03-05 15:12:38 +01:00
|
|
|
EXCLUDE_MODULES = EXCLUDE_MODULES + ("aud", )
|
2011-02-16 06:18:10 +01:00
|
|
|
|
2012-03-05 15:12:38 +01:00
|
|
|
# examples
|
|
|
|
EXAMPLES_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "examples"))
|
|
|
|
EXAMPLE_SET = set()
|
2012-03-07 18:36:38 +01:00
|
|
|
for f in os.listdir(EXAMPLES_DIR):
|
|
|
|
if f.endswith(".py"):
|
|
|
|
EXAMPLE_SET.add(os.path.splitext(f)[0])
|
2012-03-05 15:12:38 +01:00
|
|
|
EXAMPLE_SET_USED = set()
|
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
# rst files dir
|
2012-03-05 15:12:38 +01:00
|
|
|
RST_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "rst"))
|
2011-02-16 06:18:10 +01:00
|
|
|
|
2011-08-25 06:25:33 +02:00
|
|
|
# extra info, not api reference docs
|
2012-03-02 15:39:18 +01:00
|
|
|
# stored in ./rst/info_*
|
2011-08-25 06:25:33 +02:00
|
|
|
INFO_DOCS = (
|
2011-10-28 03:10:46 +02:00
|
|
|
("info_quickstart.rst", "Blender/Python Quickstart: new to blender/scripting and want to get your feet wet?"),
|
2011-08-25 06:25:33 +02:00
|
|
|
("info_overview.rst", "Blender/Python API Overview: a more complete explanation of python integration"),
|
2011-09-09 01:59:47 +02:00
|
|
|
("info_best_practice.rst", "Best Practice: Conventions to follow for writing good scripts"),
|
2012-03-07 18:36:38 +01:00
|
|
|
("info_tips_and_tricks.rst", "Tips and Tricks: Hints to help you while writing scripts for blender"),
|
2011-08-26 06:00:55 +02:00
|
|
|
("info_gotcha.rst", "Gotcha's: some of the problems you may come up against when writing scripts"),
|
2011-08-25 06:25:33 +02:00
|
|
|
)
|
2011-02-16 06:18:10 +01:00
|
|
|
|
2011-11-24 23:24:07 +01:00
|
|
|
# only support for properties atm.
|
|
|
|
RNA_BLACKLIST = {
|
2012-03-07 18:36:38 +01:00
|
|
|
# XXX messes up PDF!, really a bug but for now just workaround.
|
2012-03-15 01:12:31 +01:00
|
|
|
"UserPreferencesSystem": {"language" }
|
2011-11-24 23:24:07 +01:00
|
|
|
}
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
# --------------------configure compile time options----------------------------
|
|
|
|
|
|
|
|
# -------------------------------BLENDER----------------------------------------
|
|
|
|
|
|
|
|
blender_version_strings = [str(v) for v in bpy.app.version]
|
|
|
|
|
|
|
|
# converting bytes to strings, due to #30154
|
|
|
|
BLENDER_REVISION = str(bpy.app.build_revision, 'utf_8')
|
|
|
|
BLENDER_DATE = str(bpy.app.build_date, 'utf_8')
|
|
|
|
|
|
|
|
BLENDER_VERSION_DOTS = ".".join(blender_version_strings) # '2.62.1'
|
|
|
|
if BLENDER_REVISION != "Unknown":
|
|
|
|
BLENDER_VERSION_DOTS += " r" + BLENDER_REVISION # '2.62.1 r44584'
|
|
|
|
|
|
|
|
BLENDER_VERSION_PATH = "_".join(blender_version_strings) # '2_62_1'
|
|
|
|
if bpy.app.version_cycle == "release":
|
|
|
|
BLENDER_VERSION_PATH = "%s%s_release" % ("_".join(blender_version_strings[:2]),
|
|
|
|
bpy.app.version_char) # '2_62_release'
|
|
|
|
|
|
|
|
# --------------------------DOWNLOADABLE FILES----------------------------------
|
|
|
|
|
|
|
|
REFERENCE_NAME = "blender_python_reference_%s" % BLENDER_VERSION_PATH
|
|
|
|
REFERENCE_PATH = os.path.join(ARGS.output_dir, REFERENCE_NAME)
|
|
|
|
BLENDER_PDF_FILENAME = "%s.pdf" % REFERENCE_NAME
|
|
|
|
BLENDER_ZIP_FILENAME = "%s.zip" % REFERENCE_NAME
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# -------------------------------SPHINX-----------------------------------------
|
|
|
|
|
2012-03-08 19:36:23 +01:00
|
|
|
SPHINX_THEMES = {'bf': ['blender-org'], # , 'naiad',
|
|
|
|
'sphinx': ['agogo',
|
|
|
|
'basic',
|
|
|
|
'default',
|
|
|
|
'epub',
|
|
|
|
'haiku',
|
|
|
|
'nature',
|
|
|
|
'scrolls',
|
|
|
|
'sphinxdoc',
|
|
|
|
'traditional']}
|
|
|
|
|
|
|
|
available_themes = SPHINX_THEMES['bf'] + SPHINX_THEMES['sphinx']
|
|
|
|
if ARGS.sphinx_theme not in available_themes:
|
|
|
|
print ("Please choose a theme among: %s" % ', '.join(available_themes))
|
|
|
|
sys.exit()
|
2012-03-07 18:36:38 +01:00
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
if ARGS.sphinx_theme in SPHINX_THEMES['bf']:
|
|
|
|
SPHINX_THEME_DIR = os.path.join(ARGS.output_dir, ARGS.sphinx_theme)
|
|
|
|
SPHINX_THEME_SVN_DIR = os.path.join(SCRIPT_DIR, ARGS.sphinx_theme)
|
|
|
|
|
2012-03-08 19:36:23 +01:00
|
|
|
SPHINX_IN = os.path.join(ARGS.output_dir, "sphinx-in")
|
|
|
|
SPHINX_IN_TMP = SPHINX_IN + "-tmp"
|
|
|
|
SPHINX_OUT = os.path.join(ARGS.output_dir, "sphinx-out")
|
|
|
|
if ARGS.sphinx_named_output:
|
|
|
|
SPHINX_OUT += "_%s" % ARGS.sphinx_theme
|
2012-03-08 06:36:05 +01:00
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
# html build
|
|
|
|
if ARGS.sphinx_build:
|
|
|
|
SPHINX_BUILD = ["sphinx-build", SPHINX_IN, SPHINX_OUT]
|
|
|
|
|
|
|
|
if ARGS.sphinx_log:
|
|
|
|
SPHINX_BUILD_LOG = os.path.join(ARGS.output_dir, ".sphinx-build.log")
|
|
|
|
SPHINX_BUILD = ["sphinx-build",
|
|
|
|
"-w", SPHINX_BUILD_LOG,
|
|
|
|
SPHINX_IN, SPHINX_OUT]
|
|
|
|
|
|
|
|
# pdf build
|
|
|
|
if ARGS.sphinx_build_pdf:
|
|
|
|
SPHINX_OUT_PDF = os.path.join(ARGS.output_dir, "sphinx-out_pdf")
|
|
|
|
SPHINX_BUILD_PDF = ["sphinx-build",
|
|
|
|
"-b", "latex",
|
|
|
|
SPHINX_IN, SPHINX_OUT_PDF]
|
|
|
|
SPHINX_MAKE_PDF = ["make", "-C", SPHINX_OUT_PDF]
|
|
|
|
SPHINX_MAKE_PDF_STDOUT = None
|
|
|
|
|
|
|
|
if ARGS.sphinx_log:
|
|
|
|
SPHINX_BUILD_PDF_LOG = os.path.join(ARGS.output_dir, ".sphinx-build_pdf.log")
|
|
|
|
SPHINX_BUILD_PDF = ["sphinx-build", "-b", "latex",
|
|
|
|
"-w", SPHINX_BUILD_PDF_LOG,
|
|
|
|
SPHINX_IN, SPHINX_OUT_PDF]
|
|
|
|
|
|
|
|
sphinx_make_pdf_log = os.path.join(ARGS.output_dir, ".latex_make.log")
|
|
|
|
SPHINX_MAKE_PDF_STDOUT = open(sphinx_make_pdf_log, "w", encoding="utf-8")
|
2012-03-07 18:36:38 +01:00
|
|
|
|
|
|
|
# --------------------------------API DUMP--------------------------------------
|
|
|
|
|
2010-04-06 00:37:09 +02:00
|
|
|
# lame, python wont give some access
|
2010-08-11 19:13:39 +02:00
|
|
|
ClassMethodDescriptorType = type(dict.__dict__['fromkeys'])
|
2010-04-06 00:37:09 +02:00
|
|
|
MethodDescriptorType = type(dict.get)
|
|
|
|
GetSetDescriptorType = type(int.real)
|
2011-11-04 05:27:46 +01:00
|
|
|
from types import MemberDescriptorType
|
2010-04-06 00:37:09 +02:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
_BPY_STRUCT_FAKE = "bpy_struct"
|
2011-03-22 05:28:51 +01:00
|
|
|
_BPY_PROP_COLLECTION_FAKE = "bpy_prop_collection"
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2011-03-22 05:28:51 +01:00
|
|
|
if _BPY_PROP_COLLECTION_FAKE:
|
|
|
|
_BPY_PROP_COLLECTION_ID = ":class:`%s`" % _BPY_PROP_COLLECTION_FAKE
|
|
|
|
else:
|
|
|
|
_BPY_PROP_COLLECTION_ID = "collection"
|
2010-12-10 01:20:32 +01:00
|
|
|
|
2011-03-27 07:23:14 +02:00
|
|
|
|
2011-11-04 05:27:46 +01:00
|
|
|
def is_struct_seq(value):
|
|
|
|
return isinstance(value, tuple) and type(tuple) != tuple and hasattr(value, "n_fields")
|
|
|
|
|
|
|
|
|
2010-06-15 04:06:01 +02:00
|
|
|
def undocumented_message(module_name, type_name, identifier):
|
2010-12-10 01:20:32 +01:00
|
|
|
if str(type_name).startswith('<module'):
|
|
|
|
preloadtitle = '%s.%s' % (module_name, identifier)
|
|
|
|
else:
|
|
|
|
preloadtitle = '%s.%s.%s' % (module_name, type_name, identifier)
|
2012-03-08 19:36:23 +01:00
|
|
|
message = "Undocumented (`contribute "\
|
|
|
|
"<http://wiki.blender.org/index.php/"\
|
|
|
|
"Dev:2.5/Py/API/Generating_API_Reference/Contribute/Howto-message"\
|
|
|
|
"?action=edit"\
|
|
|
|
"§ion=new"\
|
|
|
|
"&preload=Dev:2.5/Py/API/Documentation/Contribute/Howto-message"\
|
|
|
|
"&preloadtitle=%s>`_)\n\n" % preloadtitle
|
2010-06-15 04:06:01 +02:00
|
|
|
return message
|
|
|
|
|
2010-06-12 00:41:13 +02:00
|
|
|
|
2009-12-25 16:50:53 +01:00
|
|
|
def range_str(val):
|
2010-06-15 04:06:01 +02:00
|
|
|
'''
|
|
|
|
Converts values to strings for the range directive.
|
|
|
|
(unused function it seems)
|
|
|
|
'''
|
2011-02-04 10:27:25 +01:00
|
|
|
if val < -10000000:
|
|
|
|
return '-inf'
|
|
|
|
elif val > 10000000:
|
|
|
|
return 'inf'
|
|
|
|
elif type(val) == float:
|
|
|
|
return '%g' % val
|
2009-12-25 16:50:53 +01:00
|
|
|
else:
|
|
|
|
return str(val)
|
|
|
|
|
2010-02-28 14:45:08 +01:00
|
|
|
|
2011-02-16 18:31:04 +01:00
|
|
|
def example_extract_docstring(filepath):
|
2011-09-29 14:11:58 +02:00
|
|
|
file = open(filepath, "r", encoding="utf-8")
|
2011-02-16 18:31:04 +01:00
|
|
|
line = file.readline()
|
|
|
|
line_no = 0
|
|
|
|
text = []
|
|
|
|
if line.startswith('"""'): # assume nothing here
|
|
|
|
line_no += 1
|
|
|
|
else:
|
|
|
|
file.close()
|
|
|
|
return "", 0
|
|
|
|
|
|
|
|
for line in file.readlines():
|
|
|
|
line_no += 1
|
|
|
|
if line.startswith('"""'):
|
|
|
|
break
|
|
|
|
else:
|
|
|
|
text.append(line.rstrip())
|
|
|
|
|
|
|
|
line_no += 1
|
|
|
|
file.close()
|
|
|
|
return "\n".join(text), line_no
|
|
|
|
|
|
|
|
|
2011-03-22 05:28:51 +01:00
|
|
|
def write_title(fw, text, heading_char):
|
|
|
|
fw("%s\n%s\n\n" % (text, len(text) * heading_char))
|
|
|
|
|
|
|
|
|
2010-06-15 04:06:01 +02:00
|
|
|
def write_example_ref(ident, fw, example_id, ext="py"):
|
2010-02-28 14:45:08 +01:00
|
|
|
if example_id in EXAMPLE_SET:
|
2011-02-18 09:47:37 +01:00
|
|
|
|
2011-02-16 18:31:04 +01:00
|
|
|
# extract the comment
|
2012-03-02 15:39:18 +01:00
|
|
|
filepath = os.path.join(EXAMPLES_DIR, "%s.%s" % (example_id, ext))
|
2011-02-16 18:31:04 +01:00
|
|
|
filepath_full = os.path.join(os.path.dirname(fw.__self__.name), filepath)
|
2011-02-18 09:47:37 +01:00
|
|
|
|
2011-02-16 18:31:04 +01:00
|
|
|
text, line_no = example_extract_docstring(filepath_full)
|
2011-02-18 09:47:37 +01:00
|
|
|
|
2011-02-16 18:31:04 +01:00
|
|
|
for line in text.split("\n"):
|
|
|
|
fw("%s\n" % (ident + line).rstrip())
|
|
|
|
fw("\n")
|
|
|
|
|
|
|
|
fw("%s.. literalinclude:: %s\n" % (ident, filepath))
|
2011-02-18 09:47:37 +01:00
|
|
|
if line_no > 0:
|
|
|
|
fw("%s :lines: %d-\n" % (ident, line_no))
|
2011-02-16 18:31:04 +01:00
|
|
|
fw("\n")
|
2010-02-28 14:45:08 +01:00
|
|
|
EXAMPLE_SET_USED.add(example_id)
|
|
|
|
else:
|
|
|
|
if bpy.app.debug:
|
2012-03-15 01:12:31 +01:00
|
|
|
BPY_LOGGER.debug("\tskipping example: " + example_id)
|
2010-02-28 14:45:08 +01:00
|
|
|
|
2011-02-16 18:31:04 +01:00
|
|
|
# Support for numbered files bpy.types.Operator -> bpy.types.Operator.1.py
|
|
|
|
i = 1
|
|
|
|
while True:
|
|
|
|
example_id_num = "%s.%d" % (example_id, i)
|
|
|
|
if example_id_num in EXAMPLE_SET:
|
|
|
|
write_example_ref(ident, fw, example_id_num, ext)
|
|
|
|
i += 1
|
|
|
|
else:
|
|
|
|
break
|
|
|
|
|
2010-02-28 14:45:08 +01:00
|
|
|
|
2010-01-31 22:52:26 +01:00
|
|
|
def write_indented_lines(ident, fn, text, strip=True):
|
2010-06-15 04:06:01 +02:00
|
|
|
'''
|
|
|
|
Apply same indentation to all lines in a multilines text.
|
|
|
|
'''
|
2009-12-25 16:50:53 +01:00
|
|
|
if text is None:
|
|
|
|
return
|
2011-05-28 09:47:58 +02:00
|
|
|
|
|
|
|
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:
|
2012-03-02 15:39:18 +01:00
|
|
|
# set indentation to <indent>
|
2011-05-28 09:47:58 +02:00
|
|
|
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:
|
2012-03-02 15:39:18 +01:00
|
|
|
# add <indent> number of blanks to the current indentation
|
2011-05-28 09:47:58 +02:00
|
|
|
for l in lines:
|
2010-01-31 22:52:26 +01:00
|
|
|
fn(ident + l + "\n")
|
2009-12-25 16:50:53 +01:00
|
|
|
|
2010-01-22 03:04:25 +01:00
|
|
|
|
|
|
|
def pymethod2sphinx(ident, fw, identifier, py_func):
|
|
|
|
'''
|
|
|
|
class method to sphinx
|
|
|
|
'''
|
|
|
|
arg_str = inspect.formatargspec(*inspect.getargspec(py_func))
|
|
|
|
if arg_str.startswith("(self, "):
|
|
|
|
arg_str = "(" + arg_str[7:]
|
|
|
|
func_type = "method"
|
|
|
|
elif arg_str.startswith("(cls, "):
|
|
|
|
arg_str = "(" + arg_str[6:]
|
|
|
|
func_type = "classmethod"
|
|
|
|
else:
|
|
|
|
func_type = "staticmethod"
|
|
|
|
|
|
|
|
fw(ident + ".. %s:: %s%s\n\n" % (func_type, identifier, arg_str))
|
|
|
|
if py_func.__doc__:
|
|
|
|
write_indented_lines(ident + " ", fw, py_func.__doc__)
|
|
|
|
fw("\n")
|
|
|
|
|
|
|
|
|
|
|
|
def pyfunc2sphinx(ident, fw, identifier, py_func, is_class=True):
|
|
|
|
'''
|
|
|
|
function or class method to sphinx
|
|
|
|
'''
|
|
|
|
arg_str = inspect.formatargspec(*inspect.getargspec(py_func))
|
|
|
|
|
|
|
|
if not is_class:
|
|
|
|
func_type = "function"
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-01-22 03:04:25 +01:00
|
|
|
# ther rest are class methods
|
|
|
|
elif arg_str.startswith("(self, "):
|
|
|
|
arg_str = "(" + arg_str[7:]
|
|
|
|
func_type = "method"
|
|
|
|
elif arg_str.startswith("(cls, "):
|
|
|
|
arg_str = "(" + arg_str[6:]
|
|
|
|
func_type = "classmethod"
|
|
|
|
else:
|
|
|
|
func_type = "staticmethod"
|
|
|
|
|
|
|
|
fw(ident + ".. %s:: %s%s\n\n" % (func_type, identifier, arg_str))
|
|
|
|
if py_func.__doc__:
|
2011-05-28 09:47:58 +02:00
|
|
|
write_indented_lines(ident + " ", fw, py_func.__doc__)
|
2010-01-22 03:04:25 +01:00
|
|
|
fw("\n")
|
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2011-02-04 10:27:25 +01:00
|
|
|
def py_descr2sphinx(ident, fw, descr, module_name, type_name, identifier):
|
2010-07-19 15:36:10 +02:00
|
|
|
if identifier.startswith("_"):
|
|
|
|
return
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
doc = descr.__doc__
|
|
|
|
if not doc:
|
2010-06-15 04:06:01 +02:00
|
|
|
doc = undocumented_message(module_name, type_name, identifier)
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
if type(descr) == GetSetDescriptorType:
|
|
|
|
fw(ident + ".. attribute:: %s\n\n" % identifier)
|
2010-05-30 02:24:32 +02:00
|
|
|
write_indented_lines(ident + " ", fw, doc, False)
|
2011-05-28 09:47:58 +02:00
|
|
|
fw("\n")
|
2011-11-04 16:21:34 +01:00
|
|
|
elif type(descr) == MemberDescriptorType: # same as above but use 'data'
|
2011-11-04 05:27:46 +01:00
|
|
|
fw(ident + ".. data:: %s\n\n" % identifier)
|
|
|
|
write_indented_lines(ident + " ", fw, doc, False)
|
|
|
|
fw("\n")
|
2010-08-11 19:13:39 +02:00
|
|
|
elif type(descr) in (MethodDescriptorType, ClassMethodDescriptorType):
|
2010-04-10 20:35:50 +02:00
|
|
|
write_indented_lines(ident, fw, doc, False)
|
2011-05-28 09:47:58 +02:00
|
|
|
fw("\n")
|
2010-04-10 20:35:50 +02:00
|
|
|
else:
|
2010-08-11 19:13:39 +02:00
|
|
|
raise TypeError("type was not GetSetDescriptorType, MethodDescriptorType or ClassMethodDescriptorType")
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2011-03-31 14:45:54 +02:00
|
|
|
write_example_ref(ident + " ", fw, module_name + "." + type_name + "." + identifier)
|
2010-04-10 20:35:50 +02:00
|
|
|
fw("\n")
|
|
|
|
|
2010-06-15 04:06:01 +02:00
|
|
|
|
|
|
|
def py_c_func2sphinx(ident, fw, module_name, type_name, identifier, py_func, is_class=True):
|
2010-01-22 03:04:25 +01:00
|
|
|
'''
|
|
|
|
c defined function to sphinx.
|
|
|
|
'''
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-01-22 03:04:25 +01:00
|
|
|
# dump the docstring, assume its formatted correctly
|
|
|
|
if py_func.__doc__:
|
2010-01-31 22:52:26 +01:00
|
|
|
write_indented_lines(ident, fw, py_func.__doc__, False)
|
2010-01-22 03:04:25 +01:00
|
|
|
fw("\n")
|
|
|
|
else:
|
|
|
|
fw(ident + ".. function:: %s()\n\n" % identifier)
|
2010-06-15 04:06:01 +02:00
|
|
|
fw(ident + " " + undocumented_message(module_name, type_name, identifier))
|
|
|
|
|
2011-03-14 11:31:50 +01:00
|
|
|
if is_class:
|
|
|
|
write_example_ref(ident + " ", fw, module_name + "." + type_name + "." + identifier)
|
|
|
|
else:
|
|
|
|
write_example_ref(ident + " ", fw, module_name + "." + identifier)
|
|
|
|
|
|
|
|
fw("\n")
|
|
|
|
|
2010-01-22 03:04:25 +01:00
|
|
|
|
|
|
|
def pyprop2sphinx(ident, fw, identifier, py_prop):
|
|
|
|
'''
|
|
|
|
python property to sphinx
|
|
|
|
'''
|
2010-06-28 02:06:23 +02:00
|
|
|
# readonly properties use "data" directive, variables use "attribute" directive
|
|
|
|
if py_prop.fset is None:
|
|
|
|
fw(ident + ".. data:: %s\n\n" % identifier)
|
|
|
|
else:
|
|
|
|
fw(ident + ".. attribute:: %s\n\n" % identifier)
|
2010-01-22 03:04:25 +01:00
|
|
|
write_indented_lines(ident + " ", fw, py_prop.__doc__)
|
|
|
|
if py_prop.fset is None:
|
|
|
|
fw(ident + " (readonly)\n\n")
|
|
|
|
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
def pymodule2sphinx(basepath, module_name, module, title):
|
2010-01-22 03:04:25 +01:00
|
|
|
import types
|
2010-04-10 21:06:18 +02:00
|
|
|
attribute_set = set()
|
2012-03-07 18:36:38 +01:00
|
|
|
filepath = os.path.join(basepath, module_name + ".rst")
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2011-05-28 09:47:58 +02:00
|
|
|
module_all = getattr(module, "__all__", None)
|
|
|
|
module_dir = sorted(dir(module))
|
|
|
|
|
|
|
|
if module_all:
|
|
|
|
module_dir = module_all
|
|
|
|
|
2011-09-29 14:11:58 +02:00
|
|
|
file = open(filepath, "w", encoding="utf-8")
|
2010-01-27 22:33:39 +01:00
|
|
|
|
2010-01-22 03:04:25 +01:00
|
|
|
fw = file.write
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2011-05-28 09:47:58 +02:00
|
|
|
write_title(fw, "%s (%s)" % (title, module_name), "=")
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-01-22 03:04:25 +01:00
|
|
|
fw(".. module:: %s\n\n" % module_name)
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-01-22 03:04:25 +01:00
|
|
|
if module.__doc__:
|
|
|
|
# Note, may contain sphinx syntax, dont mangle!
|
|
|
|
fw(module.__doc__.strip())
|
|
|
|
fw("\n\n")
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-02-28 14:45:08 +01:00
|
|
|
write_example_ref("", fw, module_name)
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2011-05-28 09:47:58 +02:00
|
|
|
# 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)
|
|
|
|
exec(exec_str, ns, ns)
|
|
|
|
submod = ns["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)
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
pymodule2sphinx(basepath, submod_name_full, submod, "%s submodule" % module_name)
|
2011-05-28 09:47:58 +02:00
|
|
|
del submod_ls
|
|
|
|
# done writing submodules!
|
|
|
|
|
2010-01-31 22:52:26 +01:00
|
|
|
# write members of the module
|
|
|
|
# only tested with PyStructs which are not exactly modules
|
2010-04-10 20:35:50 +02:00
|
|
|
for key, descr in sorted(type(module).__dict__.items()):
|
2010-12-06 13:36:55 +01:00
|
|
|
if key.startswith("__"):
|
|
|
|
continue
|
|
|
|
# naughty, we also add getset's into PyStructs, this is not typical py but also not incorrect.
|
2011-11-04 05:27:46 +01:00
|
|
|
|
|
|
|
# type_name is only used for examples and messages
|
2011-11-04 16:21:34 +01:00
|
|
|
type_name = str(type(module)).strip("<>").split(" ", 1)[-1][1:-1] # "<class 'bpy.app.handlers'>" --> bpy.app.handlers
|
2011-11-04 05:27:46 +01:00
|
|
|
if type(descr) == types.GetSetDescriptorType:
|
|
|
|
py_descr2sphinx("", fw, descr, module_name, type_name, key)
|
2010-12-06 13:36:55 +01:00
|
|
|
attribute_set.add(key)
|
2011-11-04 05:27:46 +01:00
|
|
|
descr_sorted = []
|
2010-12-06 13:36:55 +01:00
|
|
|
for key, descr in sorted(type(module).__dict__.items()):
|
|
|
|
if key.startswith("__"):
|
|
|
|
continue
|
|
|
|
|
2011-11-04 05:27:46 +01:00
|
|
|
if type(descr) == MemberDescriptorType:
|
2010-01-31 22:52:26 +01:00
|
|
|
if descr.__doc__:
|
2011-11-04 05:27:46 +01:00
|
|
|
value = getattr(module, key, None)
|
2011-11-05 02:48:10 +01:00
|
|
|
|
2011-11-04 05:27:46 +01:00
|
|
|
value_type = type(value)
|
|
|
|
descr_sorted.append((key, descr, value, type(value)))
|
|
|
|
# sort by the valye type
|
|
|
|
descr_sorted.sort(key=lambda descr_data: str(descr_data[3]))
|
|
|
|
for key, descr, value, value_type in descr_sorted:
|
|
|
|
|
2011-11-05 02:48:10 +01:00
|
|
|
# must be documented as a submodule
|
2011-11-04 05:27:46 +01:00
|
|
|
if is_struct_seq(value):
|
2011-11-05 02:48:10 +01:00
|
|
|
continue
|
|
|
|
|
|
|
|
type_name = value_type.__name__
|
|
|
|
py_descr2sphinx("", fw, descr, module_name, type_name, key)
|
2011-11-04 05:27:46 +01:00
|
|
|
|
|
|
|
attribute_set.add(key)
|
|
|
|
|
|
|
|
del key, descr, descr_sorted
|
2011-02-04 10:27:25 +01:00
|
|
|
|
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
|
|
|
classes = []
|
2011-07-31 05:15:37 +02:00
|
|
|
submodules = []
|
2010-01-22 03:04:25 +01:00
|
|
|
|
2011-11-04 05:27:46 +01:00
|
|
|
# use this list so we can sort by type
|
|
|
|
module_dir_value_type = []
|
|
|
|
|
2011-05-28 09:47:58 +02:00
|
|
|
for attribute in module_dir:
|
2011-11-04 05:27:46 +01:00
|
|
|
if attribute.startswith("_"):
|
|
|
|
continue
|
2010-04-10 21:06:18 +02:00
|
|
|
|
2011-11-04 05:27:46 +01:00
|
|
|
if attribute in attribute_set:
|
|
|
|
continue
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2011-11-04 05:27:46 +01:00
|
|
|
if attribute.startswith("n_"): # annoying exception, needed for bpy.app
|
|
|
|
continue
|
|
|
|
|
|
|
|
# workaround for bpy.app documenting .index() and .count()
|
|
|
|
if isinstance(module, tuple) and hasattr(tuple, attribute):
|
|
|
|
continue
|
|
|
|
|
|
|
|
value = getattr(module, attribute)
|
|
|
|
|
|
|
|
module_dir_value_type.append((attribute, value, type(value)))
|
|
|
|
|
|
|
|
# sort by str of each type
|
|
|
|
# this way lists, functions etc are grouped.
|
|
|
|
module_dir_value_type.sort(key=lambda triple: str(triple[2]))
|
|
|
|
|
|
|
|
for attribute, value, value_type in module_dir_value_type:
|
|
|
|
if value_type == types.FunctionType:
|
|
|
|
pyfunc2sphinx("", fw, attribute, value, is_class=False)
|
|
|
|
elif value_type in (types.BuiltinMethodType, types.BuiltinFunctionType): # both the same at the moment but to be future proof
|
|
|
|
# note: can't get args from these, so dump the string as is
|
|
|
|
# this means any module used like this must have fully formatted docstrings.
|
|
|
|
py_c_func2sphinx("", fw, module_name, None, attribute, value, is_class=False)
|
|
|
|
elif value_type == type:
|
|
|
|
classes.append((attribute, value))
|
|
|
|
elif issubclass(value_type, types.ModuleType):
|
|
|
|
submodules.append((attribute, value))
|
|
|
|
elif value_type in (bool, int, float, str, tuple):
|
|
|
|
# constant, not much fun we can do here except to list it.
|
|
|
|
# TODO, figure out some way to document these!
|
|
|
|
#fw(".. data:: %s\n\n" % attribute)
|
|
|
|
write_indented_lines(" ", fw, "constant value %s" % repr(value), False)
|
|
|
|
fw("\n")
|
|
|
|
else:
|
2012-03-15 01:12:31 +01:00
|
|
|
BPY_LOGGER.debug("\tnot documenting %s.%s of %r type" % (module_name, attribute, value_type.__name__))
|
2011-11-04 05:27:46 +01:00
|
|
|
continue
|
2010-04-10 21:06:18 +02:00
|
|
|
|
2011-11-04 05:27:46 +01:00
|
|
|
attribute_set.add(attribute)
|
|
|
|
# TODO, more types...
|
|
|
|
del module_dir_value_type
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2011-07-31 05:15:37 +02:00
|
|
|
# TODO, bpy_extras does this already, mathutils not.
|
2012-03-15 01:12:31 +01:00
|
|
|
'''
|
2011-07-31 05:15:37 +02:00
|
|
|
if submodules:
|
|
|
|
fw("\n"
|
|
|
|
"**********\n"
|
|
|
|
"Submodules\n"
|
|
|
|
"**********\n"
|
|
|
|
"\n"
|
|
|
|
)
|
|
|
|
for attribute, submod in submodules:
|
|
|
|
fw("* :mod:`%s.%s`\n" % (module_name, attribute))
|
|
|
|
fw("\n")
|
2012-03-15 01:12:31 +01:00
|
|
|
'''
|
2011-07-31 05:15:37 +02:00
|
|
|
|
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
|
|
|
# write collected classes now
|
2010-04-10 20:35:50 +02:00
|
|
|
for (type_name, value) in classes:
|
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
|
|
|
# May need to be its own function
|
2010-04-10 20:35:50 +02:00
|
|
|
fw(".. class:: %s\n\n" % type_name)
|
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
|
|
|
if value.__doc__:
|
2010-01-31 22:52:26 +01:00
|
|
|
write_indented_lines(" ", fw, value.__doc__, False)
|
2010-01-27 22:33:39 +01:00
|
|
|
fw("\n")
|
2010-04-10 20:35:50 +02:00
|
|
|
write_example_ref(" ", fw, module_name + "." + type_name)
|
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
descr_items = [(key, descr) for key, descr in sorted(value.__dict__.items()) if not key.startswith("__")]
|
|
|
|
|
2010-08-11 19:13:39 +02:00
|
|
|
for key, descr in descr_items:
|
2010-08-12 00:36:43 +02:00
|
|
|
if type(descr) == ClassMethodDescriptorType:
|
2010-08-11 19:13:39 +02:00
|
|
|
py_descr2sphinx(" ", fw, descr, module_name, type_name, key)
|
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
for key, descr in descr_items:
|
2010-08-12 00:36:43 +02:00
|
|
|
if type(descr) == MethodDescriptorType:
|
2010-04-10 20:35:50 +02:00
|
|
|
py_descr2sphinx(" ", fw, descr, module_name, type_name, key)
|
|
|
|
|
|
|
|
for key, descr in descr_items:
|
|
|
|
if type(descr) == GetSetDescriptorType:
|
|
|
|
py_descr2sphinx(" ", fw, descr, module_name, type_name, key)
|
|
|
|
|
Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
- Mathutils.AngleBetweenVecs --> vector.angle(other)
- Mathutils.ProjectVecs --> vector.project(other)
- Mathutils.DifferenceQuats --> quat.difference(other)
- Mathutils.Slerp --> quat.slerp(other, fac)
- Mathutils.Rand: removed, use pythons random module
- Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
- Matrix.scalePart --> Matrix.scale_part
- Matrix.translationPart --> Matrix.translation_part
- Matrix.rotationPart --> Matrix.rotation_part
- toMatrix --> to_matrix
- toEuler --> to_euler
- toQuat --> to_quat
- Vector.toTrackQuat --> Vector.to_track_quat
2010-01-25 10:44:04 +01:00
|
|
|
fw("\n\n")
|
2010-01-22 03:04:25 +01:00
|
|
|
|
|
|
|
file.close()
|
|
|
|
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
def pycontext2sphinx(basepath):
|
2011-02-15 16:37:40 +01:00
|
|
|
# Only use once. very irregular
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
filepath = os.path.join(basepath, "bpy.context.rst")
|
2011-09-29 14:11:58 +02:00
|
|
|
file = open(filepath, "w", encoding="utf-8")
|
2011-02-15 16:37:40 +01:00
|
|
|
fw = file.write
|
|
|
|
fw("Context Access (bpy.context)\n")
|
|
|
|
fw("============================\n\n")
|
|
|
|
fw(".. module:: bpy.context\n")
|
|
|
|
fw("\n")
|
|
|
|
fw("The context members available depend on the area of blender which is currently being accessed.\n")
|
|
|
|
fw("\n")
|
|
|
|
fw("Note that all context values are readonly, but may be modified through the data api or by running operators\n\n")
|
|
|
|
|
|
|
|
# nasty, get strings directly from blender because there is no other way to get it
|
|
|
|
import ctypes
|
|
|
|
|
|
|
|
context_strings = (
|
|
|
|
"screen_context_dir",
|
|
|
|
"view3d_context_dir",
|
|
|
|
"buttons_context_dir",
|
|
|
|
"image_context_dir",
|
|
|
|
"node_context_dir",
|
|
|
|
"text_context_dir",
|
|
|
|
)
|
|
|
|
|
|
|
|
# Changes in blender will force errors here
|
|
|
|
type_map = {
|
|
|
|
"active_base": ("ObjectBase", False),
|
|
|
|
"active_bone": ("Bone", False),
|
|
|
|
"active_object": ("Object", False),
|
2011-11-15 03:58:01 +01:00
|
|
|
"active_operator": ("Operator", False),
|
2011-02-15 16:37:40 +01:00
|
|
|
"active_pose_bone": ("PoseBone", False),
|
|
|
|
"armature": ("Armature", False),
|
|
|
|
"bone": ("Bone", False),
|
|
|
|
"brush": ("Brush", False),
|
|
|
|
"camera": ("Camera", False),
|
|
|
|
"cloth": ("ClothModifier", False),
|
|
|
|
"collision": ("CollisionModifier", False),
|
|
|
|
"curve": ("Curve", False),
|
2011-11-15 03:58:01 +01:00
|
|
|
"dynamic_paint": ("DynamicPaintModifier", False),
|
2011-02-15 16:37:40 +01:00
|
|
|
"edit_bone": ("EditBone", False),
|
|
|
|
"edit_image": ("Image", False),
|
|
|
|
"edit_object": ("Object", False),
|
|
|
|
"edit_text": ("Text", False),
|
|
|
|
"editable_bones": ("EditBone", True),
|
|
|
|
"fluid": ("FluidSimulationModifier", False),
|
2011-04-01 06:22:30 +02:00
|
|
|
"image_paint_object": ("Object", False),
|
2011-02-15 16:37:40 +01:00
|
|
|
"lamp": ("Lamp", False),
|
|
|
|
"lattice": ("Lattice", False),
|
|
|
|
"material": ("Material", False),
|
|
|
|
"material_slot": ("MaterialSlot", False),
|
|
|
|
"mesh": ("Mesh", False),
|
|
|
|
"meta_ball": ("MetaBall", False),
|
|
|
|
"object": ("Object", False),
|
|
|
|
"particle_edit_object": ("Object", False),
|
|
|
|
"particle_system": ("ParticleSystem", False),
|
|
|
|
"particle_system_editable": ("ParticleSystem", False),
|
|
|
|
"pose_bone": ("PoseBone", False),
|
|
|
|
"scene": ("Scene", False),
|
|
|
|
"sculpt_object": ("Object", False),
|
|
|
|
"selectable_bases": ("ObjectBase", True),
|
|
|
|
"selectable_objects": ("Object", True),
|
|
|
|
"selected_bases": ("ObjectBase", True),
|
|
|
|
"selected_bones": ("Bone", True),
|
|
|
|
"selected_editable_bases": ("ObjectBase", True),
|
|
|
|
"selected_editable_bones": ("Bone", True),
|
|
|
|
"selected_editable_objects": ("Object", True),
|
|
|
|
"selected_editable_sequences": ("Sequence", True),
|
|
|
|
"selected_nodes": ("Node", True),
|
|
|
|
"selected_objects": ("Object", True),
|
|
|
|
"selected_pose_bones": ("PoseBone", True),
|
|
|
|
"selected_sequences": ("Sequence", True),
|
|
|
|
"sequences": ("Sequence", True),
|
|
|
|
"smoke": ("SmokeModifier", False),
|
|
|
|
"soft_body": ("SoftBodyModifier", False),
|
2011-09-06 02:12:34 +02:00
|
|
|
"speaker": ("Speaker", False),
|
2011-02-15 16:37:40 +01:00
|
|
|
"texture": ("Texture", False),
|
|
|
|
"texture_slot": ("MaterialTextureSlot", False),
|
2011-11-15 03:58:01 +01:00
|
|
|
"texture_user": ("ID", False),
|
2011-02-15 16:37:40 +01:00
|
|
|
"vertex_paint_object": ("Object", False),
|
|
|
|
"visible_bases": ("ObjectBase", True),
|
|
|
|
"visible_bones": ("Object", True),
|
|
|
|
"visible_objects": ("Object", True),
|
|
|
|
"visible_pose_bones": ("PoseBone", True),
|
|
|
|
"weight_paint_object": ("Object", False),
|
|
|
|
"world": ("World", False),
|
|
|
|
}
|
|
|
|
|
|
|
|
unique = set()
|
|
|
|
blend_cdll = ctypes.CDLL("")
|
|
|
|
for ctx_str in context_strings:
|
|
|
|
subsection = "%s Context" % ctx_str.split("_")[0].title()
|
|
|
|
fw("\n%s\n%s\n\n" % (subsection, (len(subsection) * '-')))
|
|
|
|
|
|
|
|
attr = ctypes.addressof(getattr(blend_cdll, ctx_str))
|
|
|
|
c_char_p_p = ctypes.POINTER(ctypes.c_char_p)
|
|
|
|
char_array = c_char_p_p.from_address(attr)
|
|
|
|
i = 0
|
|
|
|
while char_array[i] is not None:
|
2011-11-17 05:05:54 +01:00
|
|
|
member = ctypes.string_at(char_array[i]).decode(encoding="ascii")
|
2011-02-15 16:37:40 +01:00
|
|
|
fw(".. data:: %s\n\n" % member)
|
|
|
|
member_type, is_seq = type_map[member]
|
|
|
|
fw(" :type: %s :class:`bpy.types.%s`\n\n" % ("sequence of " if is_seq else "", member_type))
|
|
|
|
unique.add(member)
|
|
|
|
i += 1
|
|
|
|
|
|
|
|
# generate typemap...
|
|
|
|
# for member in sorted(unique):
|
|
|
|
# print(' "%s": ("", False),' % member)
|
|
|
|
if len(type_map) > len(unique):
|
|
|
|
raise Exception("Some types are not used: %s" % str([member for member in type_map if member not in unique]))
|
|
|
|
else:
|
2011-02-16 03:25:03 +01:00
|
|
|
pass # will have raised an error above
|
2011-02-15 16:37:40 +01:00
|
|
|
|
2011-02-22 06:23:20 +01:00
|
|
|
file.close()
|
|
|
|
|
2011-02-15 16:37:40 +01:00
|
|
|
|
2011-09-16 04:42:50 +02:00
|
|
|
def pyrna_enum2sphinx(prop, use_empty_descriptions=False):
|
2012-03-15 01:12:31 +01:00
|
|
|
'''
|
|
|
|
write a bullet point list of enum + descriptions
|
|
|
|
'''
|
2011-09-15 18:15:24 +02:00
|
|
|
|
|
|
|
if use_empty_descriptions:
|
|
|
|
ok = True
|
|
|
|
else:
|
|
|
|
ok = False
|
|
|
|
for identifier, name, description in prop.enum_items:
|
|
|
|
if description:
|
|
|
|
ok = True
|
|
|
|
break
|
|
|
|
|
|
|
|
if ok:
|
|
|
|
return "".join(["* ``%s`` %s.\n" %
|
|
|
|
(identifier,
|
|
|
|
", ".join(val for val in (name, description) if val),
|
|
|
|
)
|
|
|
|
for identifier, name, description in prop.enum_items
|
|
|
|
])
|
|
|
|
else:
|
|
|
|
return ""
|
|
|
|
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
def pyrna2sphinx(basepath):
|
2012-03-15 01:12:31 +01:00
|
|
|
'''
|
|
|
|
bpy.types and bpy.ops
|
|
|
|
'''
|
2009-12-25 16:50:53 +01:00
|
|
|
structs, funcs, ops, props = rna_info.BuildRNAInfo()
|
2011-02-16 06:18:10 +01:00
|
|
|
if FILTER_BPY_TYPES is not None:
|
|
|
|
structs = {k: v for k, v in structs.items() if k[1] in FILTER_BPY_TYPES}
|
2009-12-25 16:50:53 +01:00
|
|
|
|
2011-02-16 06:18:10 +01:00
|
|
|
if FILTER_BPY_OPS is not None:
|
|
|
|
ops = {k: v for k, v in ops.items() if v.module_name in FILTER_BPY_OPS}
|
2009-12-25 16:50:53 +01:00
|
|
|
|
2009-12-26 17:47:25 +01:00
|
|
|
def write_param(ident, fw, prop, is_return=False):
|
|
|
|
if is_return:
|
|
|
|
id_name = "return"
|
|
|
|
id_type = "rtype"
|
2011-03-22 05:28:51 +01:00
|
|
|
kwargs = {"as_ret": True}
|
2010-01-18 11:45:54 +01:00
|
|
|
identifier = ""
|
2009-12-25 16:50:53 +01:00
|
|
|
else:
|
2009-12-26 17:47:25 +01:00
|
|
|
id_name = "arg"
|
|
|
|
id_type = "type"
|
2011-03-22 05:28:51 +01:00
|
|
|
kwargs = {"as_arg": True}
|
2010-01-18 11:45:54 +01:00
|
|
|
identifier = " %s" % prop.identifier
|
2009-12-25 16:50:53 +01:00
|
|
|
|
2011-03-22 05:28:51 +01:00
|
|
|
kwargs["class_fmt"] = ":class:`%s`"
|
|
|
|
|
|
|
|
kwargs["collection_id"] = _BPY_PROP_COLLECTION_ID
|
|
|
|
|
2010-01-18 11:45:54 +01:00
|
|
|
type_descr = prop.get_type_description(**kwargs)
|
2011-09-15 18:15:24 +02:00
|
|
|
|
|
|
|
enum_text = pyrna_enum2sphinx(prop)
|
|
|
|
|
|
|
|
if prop.name or prop.description or enum_text:
|
|
|
|
fw(ident + ":%s%s:\n\n" % (id_name, identifier))
|
|
|
|
|
|
|
|
if prop.name or prop.description:
|
|
|
|
fw(ident + " " + ", ".join(val for val in (prop.name, prop.description) if val) + "\n\n")
|
|
|
|
|
|
|
|
# special exception, cant use genric code here for enums
|
|
|
|
if enum_text:
|
|
|
|
write_indented_lines(ident + " ", fw, enum_text)
|
|
|
|
fw("\n")
|
|
|
|
del enum_text
|
|
|
|
# end enum exception
|
|
|
|
|
2010-01-18 11:45:54 +01:00
|
|
|
fw(ident + ":%s%s: %s\n" % (id_type, identifier, type_descr))
|
2009-12-25 16:50:53 +01:00
|
|
|
|
|
|
|
def write_struct(struct):
|
|
|
|
#if not struct.identifier.startswith("Sc") and not struct.identifier.startswith("I"):
|
|
|
|
# return
|
|
|
|
|
2010-01-02 20:01:19 +01:00
|
|
|
#if not struct.identifier == "Object":
|
|
|
|
# return
|
2009-12-25 16:50:53 +01:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
filepath = os.path.join(basepath, "bpy.types.%s.rst" % struct.identifier)
|
2011-09-29 14:11:58 +02:00
|
|
|
file = open(filepath, "w", encoding="utf-8")
|
2009-12-25 16:50:53 +01:00
|
|
|
fw = file.write
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
base_id = getattr(struct.base, "identifier", "")
|
2011-11-24 23:24:07 +01:00
|
|
|
struct_id = struct.identifier
|
2010-04-10 20:35:50 +02:00
|
|
|
|
|
|
|
if _BPY_STRUCT_FAKE:
|
|
|
|
if not base_id:
|
|
|
|
base_id = _BPY_STRUCT_FAKE
|
|
|
|
|
|
|
|
if base_id:
|
2011-11-24 23:24:07 +01:00
|
|
|
title = "%s(%s)" % (struct_id, base_id)
|
2009-12-25 16:50:53 +01:00
|
|
|
else:
|
2011-11-24 23:24:07 +01:00
|
|
|
title = struct_id
|
2009-12-25 16:50:53 +01:00
|
|
|
|
2011-03-22 05:28:51 +01:00
|
|
|
write_title(fw, title, "=")
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2009-12-25 16:50:53 +01:00
|
|
|
fw(".. module:: bpy.types\n\n")
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2011-02-18 09:47:37 +01:00
|
|
|
# docs first?, ok
|
2011-11-24 23:24:07 +01:00
|
|
|
write_example_ref("", fw, "bpy.types.%s" % struct_id)
|
2011-02-16 18:31:04 +01:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
base_ids = [base.identifier for base in struct.get_bases()]
|
|
|
|
|
|
|
|
if _BPY_STRUCT_FAKE:
|
|
|
|
base_ids.append(_BPY_STRUCT_FAKE)
|
|
|
|
|
|
|
|
base_ids.reverse()
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
if base_ids:
|
|
|
|
if len(base_ids) > 1:
|
2009-12-25 16:50:53 +01:00
|
|
|
fw("base classes --- ")
|
|
|
|
else:
|
|
|
|
fw("base class --- ")
|
|
|
|
|
2010-09-19 09:07:14 +02:00
|
|
|
fw(", ".join((":class:`%s`" % base_id) for base_id in base_ids))
|
2009-12-25 16:50:53 +01:00
|
|
|
fw("\n\n")
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
subclass_ids = [s.identifier for s in structs.values() if s.base is struct if not rna_info.rna_id_ignore(s.identifier)]
|
|
|
|
if subclass_ids:
|
2010-09-19 09:07:14 +02:00
|
|
|
fw("subclasses --- \n" + ", ".join((":class:`%s`" % s) for s in subclass_ids) + "\n\n")
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
base_id = getattr(struct.base, "identifier", "")
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
if _BPY_STRUCT_FAKE:
|
|
|
|
if not base_id:
|
|
|
|
base_id = _BPY_STRUCT_FAKE
|
2009-12-25 16:50:53 +01:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
if base_id:
|
2011-11-24 23:24:07 +01:00
|
|
|
fw(".. class:: %s(%s)\n\n" % (struct_id, base_id))
|
2009-12-25 16:50:53 +01:00
|
|
|
else:
|
2011-11-24 23:24:07 +01:00
|
|
|
fw(".. class:: %s\n\n" % struct_id)
|
2009-12-25 16:50:53 +01:00
|
|
|
|
|
|
|
fw(" %s\n\n" % struct.description)
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-06-28 02:06:23 +02:00
|
|
|
# properties sorted in alphabetical order
|
2010-07-15 13:51:43 +02:00
|
|
|
sorted_struct_properties = struct.properties[:]
|
|
|
|
sorted_struct_properties.sort(key=lambda prop: prop.identifier)
|
|
|
|
|
2011-11-24 23:24:07 +01:00
|
|
|
# support blacklisting props
|
|
|
|
struct_blacklist = RNA_BLACKLIST.get(struct_id, ())
|
|
|
|
|
2010-06-28 02:06:23 +02:00
|
|
|
for prop in sorted_struct_properties:
|
2011-11-24 23:24:07 +01:00
|
|
|
|
|
|
|
# support blacklisting props
|
|
|
|
if prop.identifier in struct_blacklist:
|
|
|
|
continue
|
|
|
|
|
2011-03-22 05:28:51 +01:00
|
|
|
type_descr = prop.get_type_description(class_fmt=":class:`%s`", collection_id=_BPY_PROP_COLLECTION_ID)
|
2010-06-28 02:06:23 +02:00
|
|
|
# readonly properties use "data" directive, variables properties use "attribute" directive
|
|
|
|
if 'readonly' in type_descr:
|
|
|
|
fw(" .. data:: %s\n\n" % prop.identifier)
|
|
|
|
else:
|
|
|
|
fw(" .. attribute:: %s\n\n" % prop.identifier)
|
2009-12-26 17:47:25 +01:00
|
|
|
if prop.description:
|
|
|
|
fw(" %s\n\n" % prop.description)
|
2011-09-20 20:29:19 +02:00
|
|
|
|
2011-09-15 18:15:24 +02:00
|
|
|
# special exception, cant use genric code here for enums
|
|
|
|
if prop.type == "enum":
|
|
|
|
enum_text = pyrna_enum2sphinx(prop)
|
|
|
|
if enum_text:
|
|
|
|
write_indented_lines(" ", fw, enum_text)
|
|
|
|
fw("\n")
|
|
|
|
del enum_text
|
|
|
|
# end enum exception
|
|
|
|
|
2010-06-02 23:28:17 +02:00
|
|
|
fw(" :type: %s\n\n" % type_descr)
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2009-12-25 16:50:53 +01:00
|
|
|
# python attributes
|
|
|
|
py_properties = struct.get_py_properties()
|
|
|
|
py_prop = None
|
|
|
|
for identifier, py_prop in py_properties:
|
2010-01-22 03:04:25 +01:00
|
|
|
pyprop2sphinx(" ", fw, identifier, py_prop)
|
2009-12-25 16:50:53 +01:00
|
|
|
del py_properties, py_prop
|
|
|
|
|
|
|
|
for func in struct.functions:
|
2010-09-19 09:07:14 +02:00
|
|
|
args_str = ", ".join(prop.get_arg_default(force=False) for prop in func.args)
|
2009-12-25 16:50:53 +01:00
|
|
|
|
2010-08-17 16:32:14 +02:00
|
|
|
fw(" .. %s:: %s(%s)\n\n" % ("classmethod" if func.is_classmethod else "method", func.identifier, args_str))
|
2009-12-25 16:50:53 +01:00
|
|
|
fw(" %s\n\n" % func.description)
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2009-12-25 16:50:53 +01:00
|
|
|
for prop in func.args:
|
2009-12-26 17:47:25 +01:00
|
|
|
write_param(" ", fw, prop)
|
|
|
|
|
2010-01-02 19:55:07 +01:00
|
|
|
if len(func.return_values) == 1:
|
|
|
|
write_param(" ", fw, func.return_values[0], is_return=True)
|
2011-02-04 10:27:25 +01:00
|
|
|
elif func.return_values: # multiple return values
|
2010-09-19 09:07:14 +02:00
|
|
|
fw(" :return (%s):\n" % ", ".join(prop.identifier for prop in func.return_values))
|
2010-01-02 19:55:07 +01:00
|
|
|
for prop in func.return_values:
|
2011-09-15 18:15:24 +02:00
|
|
|
# TODO, pyrna_enum2sphinx for multiple return values... actually dont think we even use this but still!!!
|
2011-03-22 05:28:51 +01:00
|
|
|
type_descr = prop.get_type_description(as_ret=True, class_fmt=":class:`%s`", collection_id=_BPY_PROP_COLLECTION_ID)
|
2010-01-02 19:55:07 +01:00
|
|
|
descr = prop.description
|
|
|
|
if not descr:
|
|
|
|
descr = prop.name
|
2010-01-17 21:59:35 +01:00
|
|
|
fw(" `%s`, %s, %s\n\n" % (prop.identifier, descr, type_descr))
|
2010-01-02 19:55:07 +01:00
|
|
|
|
2011-11-24 23:24:07 +01:00
|
|
|
write_example_ref(" ", fw, "bpy.types." + struct_id + "." + func.identifier)
|
2011-08-23 13:28:18 +02:00
|
|
|
|
2009-12-26 17:47:25 +01:00
|
|
|
fw("\n")
|
2009-12-25 16:50:53 +01:00
|
|
|
|
|
|
|
# python methods
|
|
|
|
py_funcs = struct.get_py_functions()
|
|
|
|
py_func = None
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2009-12-25 16:50:53 +01:00
|
|
|
for identifier, py_func in py_funcs:
|
2010-01-22 03:04:25 +01:00
|
|
|
pyfunc2sphinx(" ", fw, identifier, py_func, is_class=True)
|
2009-12-25 16:50:53 +01:00
|
|
|
del py_funcs, py_func
|
|
|
|
|
2011-03-14 11:31:50 +01:00
|
|
|
py_funcs = struct.get_py_c_functions()
|
|
|
|
py_func = None
|
|
|
|
|
|
|
|
for identifier, py_func in py_funcs:
|
2011-11-24 23:24:07 +01:00
|
|
|
py_c_func2sphinx(" ", fw, "bpy.types", struct_id, identifier, py_func, is_class=True)
|
2011-03-14 11:31:50 +01:00
|
|
|
|
2010-04-09 22:43:58 +02:00
|
|
|
lines = []
|
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
if struct.base or _BPY_STRUCT_FAKE:
|
2010-04-09 22:43:58 +02:00
|
|
|
bases = list(reversed(struct.get_bases()))
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2010-04-09 22:43:58 +02:00
|
|
|
# props
|
|
|
|
lines[:] = []
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
if _BPY_STRUCT_FAKE:
|
|
|
|
descr_items = [(key, descr) for key, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()) if not key.startswith("__")]
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
if _BPY_STRUCT_FAKE:
|
|
|
|
for key, descr in descr_items:
|
|
|
|
if type(descr) == GetSetDescriptorType:
|
2010-09-03 11:21:40 +02:00
|
|
|
lines.append(" * :class:`%s.%s`\n" % (_BPY_STRUCT_FAKE, key))
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2010-04-09 22:43:58 +02:00
|
|
|
for base in bases:
|
|
|
|
for prop in base.properties:
|
2010-09-03 11:21:40 +02:00
|
|
|
lines.append(" * :class:`%s.%s`\n" % (base.identifier, prop.identifier))
|
2010-04-09 22:43:58 +02:00
|
|
|
|
|
|
|
for identifier, py_prop in base.get_py_properties():
|
2010-09-03 11:21:40 +02:00
|
|
|
lines.append(" * :class:`%s.%s`\n" % (base.identifier, identifier))
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-04-10 20:35:50 +02:00
|
|
|
for identifier, py_prop in base.get_py_properties():
|
2010-09-03 11:21:40 +02:00
|
|
|
lines.append(" * :class:`%s.%s`\n" % (base.identifier, identifier))
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2010-04-09 22:43:58 +02:00
|
|
|
if lines:
|
|
|
|
fw(".. rubric:: Inherited Properties\n\n")
|
2010-09-03 11:21:40 +02:00
|
|
|
|
|
|
|
fw(".. hlist::\n")
|
2010-09-03 16:53:54 +02:00
|
|
|
fw(" :columns: 2\n\n")
|
2010-09-03 11:21:40 +02:00
|
|
|
|
2010-04-09 22:43:58 +02:00
|
|
|
for line in lines:
|
|
|
|
fw(line)
|
|
|
|
fw("\n")
|
|
|
|
|
|
|
|
# funcs
|
|
|
|
lines[:] = []
|
2010-04-10 20:35:50 +02:00
|
|
|
|
|
|
|
if _BPY_STRUCT_FAKE:
|
|
|
|
for key, descr in descr_items:
|
|
|
|
if type(descr) == MethodDescriptorType:
|
2010-09-03 11:21:40 +02:00
|
|
|
lines.append(" * :class:`%s.%s`\n" % (_BPY_STRUCT_FAKE, key))
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2010-04-09 22:43:58 +02:00
|
|
|
for base in bases:
|
|
|
|
for func in base.functions:
|
2010-09-03 11:21:40 +02:00
|
|
|
lines.append(" * :class:`%s.%s`\n" % (base.identifier, func.identifier))
|
2010-04-09 22:43:58 +02:00
|
|
|
for identifier, py_func in base.get_py_functions():
|
2010-09-03 11:21:40 +02:00
|
|
|
lines.append(" * :class:`%s.%s`\n" % (base.identifier, identifier))
|
2010-04-09 22:43:58 +02:00
|
|
|
|
|
|
|
if lines:
|
|
|
|
fw(".. rubric:: Inherited Functions\n\n")
|
2010-09-03 11:21:40 +02:00
|
|
|
|
|
|
|
fw(".. hlist::\n")
|
2010-09-03 16:53:54 +02:00
|
|
|
fw(" :columns: 2\n\n")
|
2010-09-03 11:21:40 +02:00
|
|
|
|
2010-04-09 22:43:58 +02:00
|
|
|
for line in lines:
|
|
|
|
fw(line)
|
|
|
|
fw("\n")
|
|
|
|
|
2011-02-04 10:27:25 +01:00
|
|
|
lines[:] = []
|
2010-04-09 22:43:58 +02:00
|
|
|
|
2009-12-25 16:50:53 +01:00
|
|
|
if struct.references:
|
|
|
|
# use this otherwise it gets in the index for a normal heading.
|
|
|
|
fw(".. rubric:: References\n\n")
|
|
|
|
|
2010-09-03 11:21:40 +02:00
|
|
|
fw(".. hlist::\n")
|
2010-09-03 16:53:54 +02:00
|
|
|
fw(" :columns: 2\n\n")
|
2010-09-03 11:21:40 +02:00
|
|
|
|
2009-12-25 16:50:53 +01:00
|
|
|
for ref in struct.references:
|
|
|
|
ref_split = ref.split(".")
|
|
|
|
if len(ref_split) > 2:
|
|
|
|
ref = ref_split[-2] + "." + ref_split[-1]
|
2010-09-03 11:21:40 +02:00
|
|
|
fw(" * :class:`%s`\n" % ref)
|
2009-12-25 16:50:53 +01:00
|
|
|
fw("\n")
|
|
|
|
|
2011-02-18 09:47:37 +01:00
|
|
|
# docs last?, disable for now
|
2011-11-24 23:24:07 +01:00
|
|
|
# write_example_ref("", fw, "bpy.types.%s" % struct_id)
|
2011-02-22 06:23:20 +01:00
|
|
|
file.close()
|
2011-02-18 09:47:37 +01:00
|
|
|
|
2011-02-16 06:18:10 +01:00
|
|
|
if "bpy.types" not in EXCLUDE_MODULES:
|
|
|
|
for struct in structs.values():
|
|
|
|
# TODO, rna_info should filter these out!
|
|
|
|
if "_OT_" in struct.identifier:
|
|
|
|
continue
|
|
|
|
write_struct(struct)
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2011-03-22 05:28:51 +01:00
|
|
|
def fake_bpy_type(class_value, class_name, descr_str, use_subclasses=True):
|
2012-03-07 18:36:38 +01:00
|
|
|
filepath = os.path.join(basepath, "bpy.types.%s.rst" % class_name)
|
2011-09-29 14:11:58 +02:00
|
|
|
file = open(filepath, "w", encoding="utf-8")
|
2011-02-16 06:18:10 +01:00
|
|
|
fw = file.write
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2011-03-22 05:28:51 +01:00
|
|
|
write_title(fw, class_name, "=")
|
|
|
|
|
2011-02-16 06:18:10 +01:00
|
|
|
fw(".. module:: bpy.types\n")
|
|
|
|
fw("\n")
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2011-03-22 05:28:51 +01:00
|
|
|
if use_subclasses:
|
|
|
|
subclass_ids = [s.identifier for s in structs.values() if s.base is None if not rna_info.rna_id_ignore(s.identifier)]
|
|
|
|
if subclass_ids:
|
|
|
|
fw("subclasses --- \n" + ", ".join((":class:`%s`" % s) for s in sorted(subclass_ids)) + "\n\n")
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2011-03-22 05:28:51 +01:00
|
|
|
fw(".. class:: %s\n\n" % class_name)
|
|
|
|
fw(" %s\n\n" % descr_str)
|
2011-02-16 06:18:10 +01:00
|
|
|
fw(" .. note::\n\n")
|
2011-03-22 05:28:51 +01:00
|
|
|
fw(" Note that bpy.types.%s is not actually available from within blender, it only exists for the purpose of documentation.\n\n" % class_name)
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2011-03-22 05:28:51 +01:00
|
|
|
descr_items = [(key, descr) for key, descr in sorted(class_value.__dict__.items()) if not key.startswith("__")]
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2011-02-16 06:18:10 +01:00
|
|
|
for key, descr in descr_items:
|
|
|
|
if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
|
2011-03-22 05:28:51 +01:00
|
|
|
py_descr2sphinx(" ", fw, descr, "bpy.types", class_name, key)
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2011-02-16 06:18:10 +01:00
|
|
|
for key, descr in descr_items:
|
|
|
|
if type(descr) == GetSetDescriptorType:
|
2011-03-22 05:28:51 +01:00
|
|
|
py_descr2sphinx(" ", fw, descr, "bpy.types", class_name, key)
|
2011-02-22 06:23:20 +01:00
|
|
|
file.close()
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2011-03-22 05:28:51 +01:00
|
|
|
# write fake classes
|
|
|
|
if _BPY_STRUCT_FAKE:
|
|
|
|
class_value = bpy.types.Struct.__bases__[0]
|
|
|
|
fake_bpy_type(class_value, _BPY_STRUCT_FAKE, "built-in base class for all classes in bpy.types.", use_subclasses=True)
|
|
|
|
|
|
|
|
if _BPY_PROP_COLLECTION_FAKE:
|
|
|
|
class_value = bpy.data.objects.__class__
|
|
|
|
fake_bpy_type(class_value, _BPY_PROP_COLLECTION_FAKE, "built-in class used for all collections.", use_subclasses=False)
|
|
|
|
|
2010-06-04 15:47:56 +02:00
|
|
|
# operators
|
2009-12-25 16:50:53 +01:00
|
|
|
def write_ops():
|
2011-05-05 16:45:24 +02:00
|
|
|
API_BASEURL = "http://svn.blender.org/svnroot/bf-blender/trunk/blender/release/scripts"
|
|
|
|
API_BASEURL_ADDON = "http://svn.blender.org/svnroot/bf-extensions/trunk/py/scripts"
|
|
|
|
API_BASEURL_ADDON_CONTRIB = "http://svn.blender.org/svnroot/bf-extensions/contrib/py/scripts"
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2011-02-22 06:23:20 +01:00
|
|
|
op_modules = {}
|
|
|
|
for op in ops.values():
|
|
|
|
op_modules.setdefault(op.module_name, []).append(op)
|
|
|
|
del op
|
2011-02-25 17:19:50 +01:00
|
|
|
|
2011-02-22 06:23:20 +01:00
|
|
|
for op_module_name, ops_mod in op_modules.items():
|
2012-03-07 18:36:38 +01:00
|
|
|
filepath = os.path.join(basepath, "bpy.ops.%s.rst" % op_module_name)
|
2011-09-29 14:11:58 +02:00
|
|
|
file = open(filepath, "w", encoding="utf-8")
|
2011-02-22 06:23:20 +01:00
|
|
|
fw = file.write
|
|
|
|
|
|
|
|
title = "%s Operators" % op_module_name.replace("_", " ").title()
|
2011-03-22 05:28:51 +01:00
|
|
|
|
|
|
|
write_title(fw, title, "=")
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2011-02-22 06:23:20 +01:00
|
|
|
fw(".. module:: bpy.ops.%s\n\n" % op_module_name)
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2011-02-22 06:23:20 +01:00
|
|
|
ops_mod.sort(key=lambda op: op.func_name)
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2011-02-22 06:23:20 +01:00
|
|
|
for op in ops_mod:
|
|
|
|
args_str = ", ".join(prop.get_arg_default(force=True) for prop in op.args)
|
|
|
|
fw(".. function:: %s(%s)\n\n" % (op.func_name, args_str))
|
2010-04-10 20:35:50 +02:00
|
|
|
|
2011-02-22 06:23:20 +01:00
|
|
|
# if the description isn't valid, we output the standard warning
|
|
|
|
# with a link to the wiki so that people can help
|
|
|
|
if not op.description or op.description == "(undocumented operator)":
|
|
|
|
operator_description = undocumented_message('bpy.ops', op.module_name, op.func_name)
|
|
|
|
else:
|
|
|
|
operator_description = op.description
|
2010-06-12 00:41:13 +02:00
|
|
|
|
2011-02-22 06:23:20 +01:00
|
|
|
fw(" %s\n\n" % operator_description)
|
|
|
|
for prop in op.args:
|
|
|
|
write_param(" ", fw, prop)
|
|
|
|
if op.args:
|
|
|
|
fw("\n")
|
2010-06-12 00:41:13 +02:00
|
|
|
|
2011-02-22 06:23:20 +01:00
|
|
|
location = op.get_location()
|
|
|
|
if location != (None, None):
|
2011-05-05 16:45:24 +02:00
|
|
|
if location[0].startswith("addons_contrib" + os.sep):
|
|
|
|
url_base = API_BASEURL_ADDON_CONTRIB
|
|
|
|
elif location[0].startswith("addons" + os.sep):
|
|
|
|
url_base = API_BASEURL_ADDON
|
|
|
|
else:
|
|
|
|
url_base = API_BASEURL
|
|
|
|
|
2012-03-08 06:36:05 +01:00
|
|
|
fw(" :file: `%s <%s/%s>`_:%d\n\n" % (location[0],
|
|
|
|
url_base,
|
|
|
|
location[0],
|
2012-03-07 18:36:38 +01:00
|
|
|
location[1]))
|
2009-12-26 17:47:25 +01:00
|
|
|
|
2011-02-22 06:23:20 +01:00
|
|
|
file.close()
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2011-02-16 06:18:10 +01:00
|
|
|
if "bpy.ops" not in EXCLUDE_MODULES:
|
|
|
|
write_ops()
|
|
|
|
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
def write_sphinx_conf_py(basepath):
|
|
|
|
'''
|
|
|
|
Write sphinx's conf.py
|
|
|
|
'''
|
|
|
|
filepath = os.path.join(basepath, "conf.py")
|
2011-09-29 14:11:58 +02:00
|
|
|
file = open(filepath, "w", encoding="utf-8")
|
2011-02-16 06:18:10 +01:00
|
|
|
fw = file.write
|
2012-03-08 06:36:05 +01:00
|
|
|
|
2011-02-16 06:18:10 +01:00
|
|
|
fw("project = 'Blender'\n")
|
|
|
|
# fw("master_doc = 'index'\n")
|
|
|
|
fw("copyright = u'Blender Foundation'\n")
|
2012-03-07 18:36:38 +01:00
|
|
|
fw("version = '%s - API'\n" % BLENDER_VERSION_DOTS)
|
|
|
|
fw("release = '%s - API'\n" % BLENDER_VERSION_DOTS)
|
2011-09-20 03:35:39 +02:00
|
|
|
|
2012-03-08 19:36:23 +01:00
|
|
|
if ARGS.sphinx_theme != 'default':
|
|
|
|
fw("html_theme = '%s'\n" % ARGS.sphinx_theme)
|
2011-09-20 03:35:39 +02:00
|
|
|
|
2012-03-08 19:36:23 +01:00
|
|
|
if ARGS.sphinx_theme in SPHINX_THEMES['bf']:
|
|
|
|
fw("html_theme_path = ['../']\n")
|
2011-10-12 01:27:01 +02:00
|
|
|
# copied with the theme, exclude else we get an error [#28873]
|
2012-03-08 19:36:23 +01:00
|
|
|
fw("html_favicon = 'favicon.ico'\n") # in <theme>/static/
|
2011-10-12 01:27:01 +02:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# not helpful since the source is generated, adds to upload size.
|
2011-02-16 06:18:10 +01:00
|
|
|
fw("html_copy_source = False\n")
|
|
|
|
fw("\n")
|
2012-03-08 06:36:05 +01:00
|
|
|
|
2011-02-16 06:18:10 +01:00
|
|
|
# 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()
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
|
|
|
|
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")
|
2011-09-29 14:11:58 +02:00
|
|
|
file = open(filepath, "w", encoding="utf-8")
|
2011-02-16 06:18:10 +01:00
|
|
|
fw = file.write
|
|
|
|
|
|
|
|
fw("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n")
|
|
|
|
fw(" Blender Documentation contents\n")
|
|
|
|
fw("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n")
|
|
|
|
fw("\n")
|
2012-03-15 01:12:31 +01:00
|
|
|
fw("Welcome, this document is an API reference for Blender %s, built %s.\n" % (BLENDER_VERSION_DOTS, BLENDER_DATE))
|
2011-02-16 06:18:10 +01:00
|
|
|
fw("\n")
|
2012-02-10 16:00:55 +01:00
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
# fw("`A PDF version of this document is also available <%s>`_\n" % BLENDER_PDF_FILENAME)
|
|
|
|
fw("`A compressed ZIP file of this site is available <%s>`_\n" % BLENDER_ZIP_FILENAME)
|
2011-04-13 16:43:11 +02:00
|
|
|
|
|
|
|
fw("\n")
|
|
|
|
|
2011-08-25 06:25:33 +02:00
|
|
|
if not EXCLUDE_INFO_DOCS:
|
|
|
|
fw("============================\n")
|
|
|
|
fw("Blender/Python Documentation\n")
|
|
|
|
fw("============================\n")
|
|
|
|
fw("\n")
|
|
|
|
fw("\n")
|
|
|
|
fw(".. toctree::\n")
|
|
|
|
fw(" :maxdepth: 1\n\n")
|
|
|
|
for info, info_desc in INFO_DOCS:
|
|
|
|
fw(" %s <%s>\n\n" % (info_desc, info))
|
|
|
|
fw("\n")
|
2011-02-16 06:18:10 +01:00
|
|
|
|
|
|
|
fw("===================\n")
|
|
|
|
fw("Application Modules\n")
|
|
|
|
fw("===================\n")
|
|
|
|
fw("\n")
|
|
|
|
fw(".. toctree::\n")
|
|
|
|
fw(" :maxdepth: 1\n\n")
|
2012-03-08 06:36:05 +01:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
app_modules = [
|
|
|
|
"bpy.context", # note: not actually a module
|
|
|
|
"bpy.data", # note: not actually a module
|
|
|
|
"bpy.ops",
|
|
|
|
"bpy.types",
|
2012-03-08 06:36:05 +01:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# py modules
|
|
|
|
"bpy.utils",
|
|
|
|
"bpy.path",
|
|
|
|
"bpy.app",
|
|
|
|
"bpy.app.handlers",
|
2012-03-08 06:36:05 +01:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# C modules
|
|
|
|
"bpy.props"
|
|
|
|
]
|
|
|
|
for mod in app_modules:
|
|
|
|
if mod not in EXCLUDE_MODULES:
|
|
|
|
fw(" %s\n\n" % mod)
|
2012-03-08 06:36:05 +01:00
|
|
|
|
2011-02-16 06:18:10 +01:00
|
|
|
fw("==================\n")
|
|
|
|
fw("Standalone Modules\n")
|
|
|
|
fw("==================\n")
|
|
|
|
fw("\n")
|
|
|
|
fw(".. toctree::\n")
|
|
|
|
fw(" :maxdepth: 1\n\n")
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
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)
|
2011-02-16 06:18:10 +01:00
|
|
|
|
|
|
|
# game engine
|
|
|
|
if "bge" not in EXCLUDE_MODULES:
|
|
|
|
fw("===================\n")
|
|
|
|
fw("Game Engine Modules\n")
|
|
|
|
fw("===================\n")
|
|
|
|
fw("\n")
|
|
|
|
fw(".. toctree::\n")
|
|
|
|
fw(" :maxdepth: 1\n\n")
|
|
|
|
fw(" bge.types.rst\n\n")
|
|
|
|
fw(" bge.logic.rst\n\n")
|
|
|
|
fw(" bge.render.rst\n\n")
|
2011-07-07 21:23:51 +02:00
|
|
|
fw(" bge.texture.rst\n\n")
|
2011-02-16 06:18:10 +01:00
|
|
|
fw(" bge.events.rst\n\n")
|
2011-07-08 04:59:25 +02:00
|
|
|
fw(" bge.constraints.rst\n\n")
|
2011-02-16 06:18:10 +01:00
|
|
|
|
2011-04-07 09:53:28 +02:00
|
|
|
# rna generated change log
|
|
|
|
fw("========\n")
|
|
|
|
fw("API Info\n")
|
|
|
|
fw("========\n")
|
|
|
|
fw("\n")
|
|
|
|
fw(".. toctree::\n")
|
|
|
|
fw(" :maxdepth: 1\n\n")
|
|
|
|
fw(" change_log.rst\n\n")
|
|
|
|
|
2011-04-13 16:43:11 +02:00
|
|
|
fw("\n")
|
|
|
|
fw("\n")
|
|
|
|
fw(".. note:: The Blender Python API has areas which are still in development.\n")
|
|
|
|
fw(" \n")
|
|
|
|
fw(" The following areas are subject to change.\n")
|
|
|
|
fw(" * operator behavior, names and arguments\n")
|
|
|
|
fw(" * mesh creation and editing functions\n")
|
|
|
|
fw(" \n")
|
|
|
|
fw(" These parts of the API are relatively stable and are unlikely to change significantly\n")
|
|
|
|
fw(" * data API, access to attributes of blender data such as mesh verts, material color, timeline frames and scene objects\n")
|
|
|
|
fw(" * user interface functions for defining buttons, creation of menus, headers, panels\n")
|
|
|
|
fw(" * render engine integration\n")
|
|
|
|
fw(" * modules: bgl, mathutils & game engine.\n")
|
|
|
|
fw("\n")
|
|
|
|
|
2011-02-16 06:18:10 +01:00
|
|
|
file.close()
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
|
|
|
|
def write_rst_bpy(basepath):
|
|
|
|
'''
|
|
|
|
Write rst file of bpy module (disabled by default)
|
|
|
|
'''
|
|
|
|
if ARGS.bpy:
|
|
|
|
filepath = os.path.join(basepath, "bpy.rst")
|
2011-09-29 14:11:58 +02:00
|
|
|
file = open(filepath, "w", encoding="utf-8")
|
2011-02-16 06:18:10 +01:00
|
|
|
fw = file.write
|
2012-03-07 18:36:38 +01:00
|
|
|
|
|
|
|
fw("\n")
|
|
|
|
|
|
|
|
title = ":mod:`bpy` --- Blender Python Module"
|
|
|
|
|
|
|
|
write_title(fw, title, "=")
|
|
|
|
|
|
|
|
fw(".. module:: bpy.types\n\n")
|
2011-02-16 06:18:10 +01:00
|
|
|
file.close()
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
|
|
|
|
def write_rst_types_index(basepath):
|
|
|
|
'''
|
|
|
|
Write the rst file of bpy.types module (index)
|
|
|
|
'''
|
2011-02-16 06:18:10 +01:00
|
|
|
if "bpy.types" not in EXCLUDE_MODULES:
|
2012-03-07 18:36:38 +01:00
|
|
|
filepath = os.path.join(basepath, "bpy.types.rst")
|
2011-09-29 14:11:58 +02:00
|
|
|
file = open(filepath, "w", encoding="utf-8")
|
2011-02-16 06:18:10 +01:00
|
|
|
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()
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
|
|
|
|
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")
|
|
|
|
file = open(filepath, "w", encoding="utf-8")
|
|
|
|
fw = file.write
|
|
|
|
fw("Operators (bpy.ops)\n")
|
|
|
|
fw("===================\n\n")
|
|
|
|
write_example_ref("", fw, "bpy.ops")
|
|
|
|
fw(".. toctree::\n")
|
|
|
|
fw(" :glob:\n\n")
|
|
|
|
fw(" bpy.ops.*\n\n")
|
|
|
|
file.close()
|
|
|
|
|
|
|
|
|
|
|
|
def write_rst_data(basepath):
|
|
|
|
'''
|
|
|
|
Write the rst file of bpy.data module
|
|
|
|
'''
|
2011-02-16 06:18:10 +01:00
|
|
|
if "bpy.data" not in EXCLUDE_MODULES:
|
|
|
|
# not actually a module, only write this file so we
|
|
|
|
# can reference in the TOC
|
2012-03-07 18:36:38 +01:00
|
|
|
filepath = os.path.join(basepath, "bpy.data.rst")
|
2011-09-29 14:11:58 +02:00
|
|
|
file = open(filepath, "w", encoding="utf-8")
|
2011-02-16 06:18:10 +01:00
|
|
|
fw = file.write
|
|
|
|
fw("Data Access (bpy.data)\n")
|
|
|
|
fw("======================\n\n")
|
|
|
|
fw(".. module:: bpy\n")
|
|
|
|
fw("\n")
|
|
|
|
fw("This module is used for all blender/python access.\n")
|
|
|
|
fw("\n")
|
|
|
|
fw(".. data:: data\n")
|
|
|
|
fw("\n")
|
|
|
|
fw(" Access to blenders internal data\n")
|
|
|
|
fw("\n")
|
|
|
|
fw(" :type: :class:`bpy.types.BlendData`\n")
|
|
|
|
fw("\n")
|
|
|
|
fw(".. literalinclude:: ../examples/bpy.data.py\n")
|
|
|
|
file.close()
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
EXAMPLE_SET_USED.add("bpy.data")
|
2011-02-16 06:18:10 +01:00
|
|
|
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
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)
|
2011-02-16 06:18:10 +01:00
|
|
|
|
2011-04-07 09:53:28 +02:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
def copy_handwritten_rsts(basepath):
|
2012-03-08 06:36:05 +01:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# info docs
|
2011-08-25 06:25:33 +02:00
|
|
|
if not EXCLUDE_INFO_DOCS:
|
|
|
|
for info, info_desc in INFO_DOCS:
|
2012-03-07 18:36:38 +01:00
|
|
|
shutil.copy2(os.path.join(RST_DIR, info), basepath)
|
2012-03-08 06:36:05 +01:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# 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"
|
2012-03-13 07:22:43 +01:00
|
|
|
|
|
|
|
# includes...
|
|
|
|
"include__bmesh",
|
2012-03-07 18:36:38 +01:00
|
|
|
]
|
|
|
|
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):
|
2011-08-25 06:25:33 +02:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
try:
|
|
|
|
os.mkdir(basepath)
|
|
|
|
except:
|
|
|
|
pass
|
2011-03-22 05:28:51 +01:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# sphinx setup
|
|
|
|
write_sphinx_conf_py(basepath)
|
2011-02-16 06:18:10 +01:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# main page
|
|
|
|
write_rst_contents(basepath)
|
2009-12-25 16:50:53 +01:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# 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)
|
2009-12-25 16:50:53 +01:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# internal modules
|
2012-03-08 06:36:05 +01:00
|
|
|
write_rst_bpy(basepath) # bpy, disabled by default
|
2012-03-07 18:36:38 +01:00
|
|
|
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)
|
2012-03-08 06:36:05 +01:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# copy the other rsts
|
|
|
|
copy_handwritten_rsts(basepath)
|
|
|
|
|
|
|
|
|
|
|
|
def align_sphinx_in_to_sphinx_in_tmp():
|
|
|
|
'''
|
|
|
|
Move changed files from SPHINX_IN_TMP to SPHINX_IN
|
|
|
|
'''
|
|
|
|
import filecmp
|
2011-02-04 10:27:25 +01:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
sphinx_in_files = set(os.listdir(SPHINX_IN))
|
|
|
|
sphinx_in_tmp_files = set(os.listdir(SPHINX_IN_TMP))
|
2012-03-05 15:12:38 +01:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# remove deprecated files that have been removed
|
|
|
|
for f in sorted(sphinx_in_files):
|
|
|
|
if f not in sphinx_in_tmp_files:
|
2012-03-15 01:12:31 +01:00
|
|
|
BPY_LOGGER.debug("\tdeprecated: %s" % f)
|
2012-03-07 18:36:38 +01:00
|
|
|
os.remove(os.path.join(SPHINX_IN, f))
|
2011-06-27 06:50:08 +02:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# 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)
|
2011-06-27 06:50:08 +02:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
do_copy = True
|
|
|
|
if f in sphinx_in_files:
|
|
|
|
if filecmp.cmp(f_from, f_to):
|
|
|
|
do_copy = False
|
2011-06-27 06:50:08 +02:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
if do_copy:
|
2012-03-15 01:12:31 +01:00
|
|
|
BPY_LOGGER.debug("\tupdating: %s" % f)
|
2012-03-07 18:36:38 +01:00
|
|
|
shutil.copy(f_from, f_to)
|
2011-06-27 06:50:08 +02:00
|
|
|
|
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
def refactor_sphinx_log(sphinx_logfile):
|
|
|
|
refactored_log = []
|
|
|
|
with open(sphinx_logfile, "r", encoding="utf-8") as original_logfile:
|
|
|
|
lines = set(original_logfile.readlines())
|
|
|
|
for line in lines:
|
|
|
|
if 'warning' in line.lower() or 'error' in line.lower():
|
|
|
|
line = line.strip().split(None, 2)
|
|
|
|
if len(line) == 3:
|
|
|
|
location, kind, msg = line
|
|
|
|
location = os.path.relpath(location, start=SPHINX_IN)
|
|
|
|
refactored_log.append((kind, location, msg))
|
|
|
|
with open(sphinx_logfile, "w", encoding="utf-8") as refactored_logfile:
|
|
|
|
for log in sorted(refactored_log):
|
|
|
|
refactored_logfile.write("%-12s %s\n %s\n" % log)
|
|
|
|
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
def main():
|
2011-06-27 06:50:08 +02:00
|
|
|
|
2012-03-08 19:36:23 +01:00
|
|
|
# dirs preparation
|
|
|
|
for dir_path in [ARGS.output_dir, SPHINX_IN]:
|
|
|
|
if not os.path.exists(dir_path):
|
|
|
|
os.mkdir(dir_path)
|
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# dump the api in rst files
|
2012-03-15 01:12:31 +01:00
|
|
|
shutil.rmtree(SPHINX_IN_TMP, True)
|
|
|
|
rna2sphinx(SPHINX_IN_TMP)
|
2012-03-07 18:36:38 +01:00
|
|
|
if ARGS.full_rebuild:
|
|
|
|
# only for full updates
|
|
|
|
shutil.rmtree(SPHINX_IN, True)
|
|
|
|
shutil.copytree(SPHINX_IN_TMP,
|
|
|
|
SPHINX_IN,
|
|
|
|
copy_function=shutil.copy)
|
2012-03-15 01:12:31 +01:00
|
|
|
if ARGS.sphinx_build:
|
|
|
|
shutil.rmtree(SPHINX_OUT, True)
|
|
|
|
if ARGS.sphinx_build_pdf:
|
|
|
|
shutil.rmtree(SPHINX_OUT_PDF, True)
|
2012-03-07 18:36:38 +01:00
|
|
|
else:
|
2012-03-15 01:12:31 +01:00
|
|
|
# move changed files in SPHINX_IN
|
2012-03-07 18:36:38 +01:00
|
|
|
align_sphinx_in_to_sphinx_in_tmp()
|
2011-06-27 06:50:08 +02:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
# report which example files weren't used
|
2011-06-27 06:50:08 +02:00
|
|
|
EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED
|
|
|
|
if EXAMPLE_SET_UNUSED:
|
2012-03-15 01:12:31 +01:00
|
|
|
BPY_LOGGER.debug("\nUnused examples found in '%s'..." % EXAMPLES_DIR)
|
2011-06-27 06:50:08 +02:00
|
|
|
for f in EXAMPLE_SET_UNUSED:
|
2012-03-15 01:12:31 +01:00
|
|
|
BPY_LOGGER.debug(" %s.py" % f)
|
|
|
|
BPY_LOGGER.debug(" %d total\n" % len(EXAMPLE_SET_UNUSED))
|
|
|
|
|
|
|
|
# copy the examples dir
|
|
|
|
examples_dir = os.path.join(ARGS.output_dir, "examples")
|
|
|
|
shutil.rmtree(examples_dir, True)
|
|
|
|
shutil.copytree(EXAMPLES_DIR,
|
|
|
|
examples_dir,
|
|
|
|
ignore=shutil.ignore_patterns(*(".svn",)))
|
2009-12-25 16:50:53 +01:00
|
|
|
|
2012-03-08 19:36:23 +01:00
|
|
|
# eventually, copy the theme in the output directory
|
|
|
|
if ARGS.sphinx_theme in SPHINX_THEMES['bf']:
|
|
|
|
if not os.path.exists(SPHINX_THEME_DIR):
|
|
|
|
shutil.copytree(SPHINX_THEME_SVN_DIR,
|
|
|
|
SPHINX_THEME_DIR,
|
|
|
|
copy_function=shutil.copy)
|
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
# eventually, build the html docs
|
2012-03-08 19:36:23 +01:00
|
|
|
if ARGS.sphinx_build:
|
|
|
|
import subprocess
|
2012-03-15 01:12:31 +01:00
|
|
|
subprocess.call(SPHINX_BUILD)
|
2012-03-08 19:36:23 +01:00
|
|
|
|
2012-03-15 01:12:31 +01:00
|
|
|
# sphinx-build log cleanup+sort
|
|
|
|
if ARGS.sphinx_log:
|
|
|
|
if os.stat(SPHINX_BUILD_LOG).st_size:
|
|
|
|
refactor_sphinx_log(SPHINX_BUILD_LOG)
|
|
|
|
|
|
|
|
# eventually, build the pdf docs
|
|
|
|
if ARGS.sphinx_build_pdf:
|
|
|
|
import subprocess
|
|
|
|
subprocess.call(SPHINX_BUILD_PDF)
|
|
|
|
subprocess.call(SPHINX_MAKE_PDF, stdout=SPHINX_MAKE_PDF_STDOUT)
|
|
|
|
# sphinx-build log cleanup+sort
|
|
|
|
if ARGS.sphinx_log:
|
|
|
|
if os.stat(SPHINX_BUILD_PDF_LOG).st_size:
|
|
|
|
refactor_sphinx_log(SPHINX_BUILD_PDF_LOG)
|
|
|
|
|
|
|
|
# eventually, prepare the dir to be deployed online (REFERENCE_PATH)
|
|
|
|
if ARGS.pack_reference:
|
|
|
|
|
|
|
|
if ARGS.sphinx_build:
|
|
|
|
# delete REFERENCE_PATH
|
|
|
|
if os.path.exists(REFERENCE_PATH):
|
|
|
|
shutil.rmtree(REFERENCE_PATH, True)
|
|
|
|
|
|
|
|
# copy SPHINX_OUT to the REFERENCE_PATH
|
|
|
|
ignores = ('.doctrees', 'objects.inv', '.buildinfo')
|
|
|
|
shutil.copytree(SPHINX_OUT,
|
|
|
|
REFERENCE_PATH,
|
|
|
|
ignore=shutil.ignore_patterns(*ignores))
|
|
|
|
|
|
|
|
# zip REFERENCE_PATH
|
|
|
|
from zipfile import ZipFile
|
|
|
|
# zip out of REFERENCE_PATH to avoid infinite loop
|
|
|
|
zip_tmp_path = os.path.join(ARGS.output_dir, BLENDER_ZIP_FILENAME)
|
|
|
|
zip_final_path = os.path.join(REFERENCE_PATH, BLENDER_ZIP_FILENAME)
|
|
|
|
with ZipFile(zip_tmp_path, 'w') as tmpzip:
|
|
|
|
for base, dirs, files in os.walk(REFERENCE_PATH):
|
|
|
|
zipbase = os.path.relpath(base, ARGS.output_dir)
|
|
|
|
for filename in files:
|
|
|
|
tmpzip.write(os.path.join(base, filename),
|
|
|
|
arcname = os.path.join(zipbase, filename))
|
|
|
|
|
|
|
|
# move the zip to REFERENCE_PATH
|
|
|
|
os.rename(zip_tmp_path, zip_final_path)
|
|
|
|
|
|
|
|
if ARGS.sphinx_build_pdf:
|
|
|
|
# copy the pdf to REFERENCE_PATH
|
|
|
|
shutil.copy(os.path.join(SPHINX_OUT_PDF, "contents.pdf"),
|
|
|
|
os.path.join(REFERENCE_PATH, BLENDER_PDF_FILENAME))
|
|
|
|
'''
|
|
|
|
TODO
|
|
|
|
1) uncomment the link to the pdf in write_rst_contents()
|
|
|
|
2) do we want to zip also zip the pdf too?
|
|
|
|
if so move the zipping after the pdf generation
|
|
|
|
|
|
|
|
3) Unused examples found in '/home/user/my/blender/builds/blender/doc/python_api/examples'...
|
|
|
|
check against patterns in -p
|
|
|
|
'''
|
|
|
|
|
2009-12-25 16:50:53 +01:00
|
|
|
sys.exit()
|
2010-07-19 15:36:10 +02:00
|
|
|
|
2012-03-07 18:36:38 +01:00
|
|
|
|
2010-07-19 15:36:10 +02:00
|
|
|
if __name__ == '__main__':
|
|
|
|
main()
|