[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [44920] trunk/blender/doc/python_api/ sphinx_doc_gen.py: == Python API docs ==
Luca Bonavita
mindrones at gmail.com
Fri Mar 16 11:49:47 CET 2012
Revision: 44920
http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=44920
Author: mindrones
Date: 2012-03-16 10:49:39 +0000 (Fri, 16 Mar 2012)
Log Message:
-----------
== Python API docs ==
Committing a patch similar to revision 44887 with fixes to my own bugs
(sorry Campbell, and thanks for reviewing :)
Fixes
------
- examples/ svn directory not removed anymore (in-source builds possible again)
- fixed "include references somehow stopped working"
+ using shutils.makearchive() to zip the file
New command line options
------------------------
-l: Log the output of the api dump and sphinx|latex warnings and errors
If given, save logs in:
* OUTPUT_DIR/.bpy.log
* OUTPUT_DIR/.sphinx-build.log
* OUTPUT_DIR/.sphinx-build_pdf.log
* OUTPUT_DIR/.latex_make.log
(using only one log directive instead of -l for bpy and -L for sphinx)
-P: builds the pdf
-R: pack the files in a dir ready for online deployment
(including the zip and the pdf eventually)
Example usage:
./blender.bin -b -P doc/python_api/sphinx_doc_gen.py -- -p bmesh* -o ./<OUTPUTDIR> -B -P -R -l
Revision Links:
--------------
http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=44887
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-16 08:46:55 UTC (rev 44919)
+++ trunk/blender/doc/python_api/sphinx_doc_gen.py 2012-03-16 10:49:39 UTC (rev 44920)
@@ -26,16 +26,16 @@
---------------------
Run this script from blenders root path once you have compiled blender
- ./blender.bin -b -noaudio -P doc/python_api/sphinx_doc_gen.py
+ ./blender.bin --background -noaudio --python doc/python_api/sphinx_doc_gen.py
This will generate python files in doc/python_api/sphinx-in/
providing ./blender.bin is or links to the blender executable
To choose sphinx-in directory:
- ./blender.bin -b -P doc/python_api/sphinx_doc_gen.py -- -o ../python_api
+ ./blender.bin --background --python 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 --background --python 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,38 @@
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("-T", "--sphinx-theme",
dest="sphinx_theme",
type=str,
@@ -135,27 +145,55 @@
# '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", "--log",
+ dest="log",
+ default=False,
+ action='store_true',
+ help=(
+ "Log the output of the api dump and sphinx|latex "
+ "warnings and errors (default=False).\n"
+ "If given, save logs in:\n"
+ "* OUTPUT_DIR/.bpy.log\n"
+ "* OUTPUT_DIR/.sphinx-build.log\n"
+ "* OUTPUT_DIR/.sphinx-build_pdf.log\n"
+ "* OUTPUT_DIR/.latex_make.log",
+ ),
+ required=False)
+
# parse only the args passed after '--'
argv = []
if "--" in sys.argv:
@@ -168,11 +206,29 @@
# ----------------------------------BPY-----------------------------------------
+BPY_LOGGER = logging.getLogger('bpy')
+BPY_LOGGER.setLevel(logging.DEBUG)
+
+if ARGS.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 +284,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 +293,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 +304,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
@@ -268,9 +324,35 @@
}
+# --------------------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',
+SPHINX_THEMES = {'bf': ['blender-org'], # , 'naiad',
'sphinx': ['agogo',
'basic',
'default',
@@ -286,38 +368,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)
+
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list