[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [44887] trunk/blender/doc/python_api/ sphinx_doc_gen.py: == Python API docs ==
Luca Bonavita
mindrones at gmail.com
Thu Mar 15 01:12:39 CET 2012
Revision: 44887
http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=44887
Author: mindrones
Date: 2012-03-15 00:12:31 +0000 (Thu, 15 Mar 2012)
Log Message:
-----------
== Python API docs ==
New command line options:
-l: logs bpy dumping problems in OUTPUT_DIR/.bpy.log
-L: logs sphinx|latex problems in:
* OUTPUT_DIR/.sphinx-build.log (sphinx building html problems)
* OUTPUT_DIR/.sphinx-build_pdf.log (sphinx building latex problems)
* OUTPUT_DIR/.latex_make.log (latex make problems)
-P: builds the pdf
-R: pack the files in a dir ready for online deployment
(including the zip and the pdf eventually)
Example usage:
./cmake/bin/blender -b -P ./blender/doc/python_api/sphinx_doc_gen.py -- -p bmesh* -l -o ./python_api -B -P -R -L
Modified Paths:
--------------
trunk/blender/doc/python_api/sphinx_doc_gen.py
Modified: trunk/blender/doc/python_api/sphinx_doc_gen.py
===================================================================
--- trunk/blender/doc/python_api/sphinx_doc_gen.py 2012-03-14 23:42:46 UTC (rev 44886)
+++ trunk/blender/doc/python_api/sphinx_doc_gen.py 2012-03-15 00:12:31 UTC (rev 44887)
@@ -35,7 +35,7 @@
./blender.bin -b -P doc/python_api/sphinx_doc_gen.py -- -o ../python_api
For quick builds:
- ./blender.bin -b -P doc/python_api/sphinx_doc_gen.py -- -q
+ ./blender.bin -b -P doc/python_api/sphinx_doc_gen.py -- -p
Sphinx: HTML generation
@@ -75,6 +75,7 @@
import sys
import inspect
import shutil
+import logging
from platform import platform
PLATFORM = platform().split('-')[0].lower() # 'linux', 'darwin', 'windows'
@@ -94,29 +95,47 @@
usage=SCRIPT_HELP_MSG
)
- # optional arguments
- parser.add_argument("-o", "--output",
- dest="output_dir",
+ # optional arguments
+ parser.add_argument("-p", "--partial",
+ dest="partial",
type=str,
- default=SCRIPT_DIR,
- # XXX, THIS ISNT WORKING, EXAMPLE SCRIPTS WILL NOT BE FOUND
- help="Path of the API docs (default=<script dir>).",
+ default="",
+ help="Use a wildcard to only build specific module(s)\n"
+ "Example: --partial bmesh*\n",
required=False)
- parser.add_argument("-B", "--sphinx-build",
- dest="sphinx_build",
+ parser.add_argument("-f", "--fullrebuild",
+ dest="full_rebuild",
default=False,
action='store_true',
- help="Run sphinx-build SPHINX_IN SPHINX_OUT (default=False)",
+ help="Rewrite all rst files in sphinx-in/ "
+ "(default=False)",
required=False)
- parser.add_argument("-N", "--sphinx-named-output",
- dest="sphinx_named_output",
+ parser.add_argument("-b", "--bpy",
+ dest="bpy",
default=False,
action='store_true',
- help="Add the theme name to the html dir name (default=False)",
+ 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",
+ required=False)
+
parser.add_argument("-T", "--sphinx-theme",
dest="sphinx_theme",
type=str,
@@ -135,27 +154,53 @@
# 'sphinxdoc', 'traditional'], # sphinx
required=False)
- parser.add_argument("-f", "--fullrebuild",
- dest="full_rebuild",
+ parser.add_argument("-N", "--sphinx-named-output",
+ dest="sphinx_named_output",
default=False,
action='store_true',
- help="Rewrite all rst files in sphinx-in/ (default=False)",
+ help="Add the theme name to the html dir name.\n"
+ "Example: \"sphinx-out_haiku\" (default=False)",
required=False)
- parser.add_argument("-p", "--partial",
- dest="partial",
- type=str,
- default="",
- help="Use a wildcard to only build spesific module(s)",
+ 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)",
required=False)
- parser.add_argument("-b", "--bpy",
- dest="bpy",
+ parser.add_argument("-P", "--sphinx-build-pdf",
+ dest="sphinx_build_pdf",
default=False,
action='store_true',
- help="Write the rst file of the bpy module (default=False)",
+ 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",
+ default=False,
+ action='store_true',
+ 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
+ required=False)
+
# parse only the args passed after '--'
argv = []
if "--" in sys.argv:
@@ -168,11 +213,29 @@
# ----------------------------------BPY-----------------------------------------
+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)
+
"""
# for quick rebuilds
rm -rf /b/doc/python_api/sphinx-* && \
-./blender.bin --background -noaudio --factory-startup --python doc/python_api/sphinx_doc_gen.py && \
+./blender.bin -b -noaudio --factory-startup -P doc/python_api/sphinx_doc_gen.py && \
sphinx-build doc/python_api/sphinx-in doc/python_api/sphinx-out
+
+or
+
+./blender.bin -b -noaudio --factory-startup -P doc/python_api/sphinx_doc_gen.py -- -f -B
"""
# Switch for quick testing so doc-builds don't take so long
@@ -228,7 +291,7 @@
del m
del fnmatch
- print("Partial Doc Build, Skipping: %s\n" % "\n ".join(sorted(EXCLUDE_MODULES)))
+ BPY_LOGGER.debug("Partial Doc Build, Skipping: %s\n" % "\n ".join(sorted(EXCLUDE_MODULES)))
#
# done filtering
@@ -237,7 +300,7 @@
try:
__import__("aud")
except ImportError:
- print("Warning: Built without 'aud' module, docs incomplete...")
+ BPY_LOGGER.debug("Warning: Built without 'aud' module, docs incomplete...")
EXCLUDE_MODULES = EXCLUDE_MODULES + ("aud", )
# examples
@@ -248,7 +311,7 @@
EXAMPLE_SET.add(os.path.splitext(f)[0])
EXAMPLE_SET_USED = set()
-#rst files dir
+# rst files dir
RST_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "rst"))
# extra info, not api reference docs
@@ -264,10 +327,36 @@
# only support for properties atm.
RNA_BLACKLIST = {
# XXX messes up PDF!, really a bug but for now just workaround.
- "UserPreferencesSystem": {"language", }
+ "UserPreferencesSystem": {"language" }
}
+# --------------------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
+
# -------------------------------SPHINX-----------------------------------------
SPHINX_THEMES = {'bf': ['blender-org'], # , 'naiad',
@@ -286,38 +375,44 @@
print ("Please choose a theme among: %s" % ', '.join(available_themes))
sys.exit()
+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)
+
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")
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list