From 0fe519f14a9bc43f4d5c8f5bbd04013f4ca5e32e Mon Sep 17 00:00:00 2001 From: Luca Bonavita Date: Mon, 5 Mar 2012 14:12:38 +0000 Subject: == Python API docs == Adding two new command line options (-f = full rebuild, -t = testing) so that we don't have to edit the file each time --- doc/python_api/sphinx_doc_gen.py | 158 ++++++++++++++++++++------------------- 1 file changed, 83 insertions(+), 75 deletions(-) (limited to 'doc/python_api/sphinx_doc_gen.py') diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index fa42c2e5888..c66c215203d 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -20,24 +20,27 @@ # -script_help_msg = """ +SCRIPT_HELP_MSG = """ API dump in RST files --------------------- Run this script from blenders root path once you have compiled blender - ./blender.bin --background -noaudio --python doc/python_api/sphinx_doc_gen.py + ./blender.bin -b -noaudio -P 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 use the -o option, putting the path after '--'. - Example: - ./cmake/bin/blender -b -P ./blender/doc/python_api/sphinx_doc_gen.py -- -o ./python_api + To choose sphinx-in directory: + ./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 Sphinx: HTML generation ----------------------- - Generate html docs by running... + After you have built doc/python_api/sphinx-in (see above), + generate html docs by running: cd doc/python_api sphinx-build sphinx-in sphinx-out @@ -46,19 +49,20 @@ Sphinx: HTML generation Sphinx: PDF generation ---------------------- - After you have built doc/python_api/sphinx-in (see above), run: + After you have built doc/python_api/sphinx-in (see above), + generate the pdf doc by running: sphinx-build -b latex doc/python_api/sphinx-in doc/python_api/sphinx-out cd doc/python_api/sphinx-out make - + """ try: import bpy # blender module except: - print("\nError, this script must run from inside blender") - print(script_help_msg) + print("\nERROR: this script must run from inside Blender") + print(SCRIPT_HELP_MSG) import sys sys.exit() @@ -73,19 +77,58 @@ import shutil from platform import platform PLATFORM = platform().split('-')[0].lower() # 'linux', 'darwin', 'windows' -# this script dir -SCRIPT_DIR = os.path.dirname(__file__) -# examples -EXAMPLES_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "examples")) -EXAMPLE_SET = set() -EXAMPLE_SET_USED = set() +def handle_args(): + ''' + Get the args passed to Blender after "--", ignored by Blender + ''' -#rst files dir -RST_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "rst")) + import argparse + + # When --help is given, print the usage text + parser = argparse.ArgumentParser( + formatter_class=argparse.RawDescriptionHelpFormatter, + usage=SCRIPT_HELP_MSG + ) + + parser.add_argument("-o", "--output", + dest="output_dir", + type=str, + help="Path of the API docs (optional)", + required=False) + + parser.add_argument("-f", "--fullrebuild", + dest="full_rebuild", + default=False, + action='store_true', + help="Rewrite all rst files in sphinx-in/ (optional)", + required=False) + + parser.add_argument("-t", "--testbuild", + dest="test_build", + default=False, + action='store_true', + help="Build only a small part of the API (optional)", + required=False) + + argv = [] + if "--" in sys.argv: + argv = sys.argv[sys.argv.index("--") + 1:] # get all args after "--" + + return parser.parse_args(argv) + +SCRIPT_ARGS = handle_args() +SCRIPT_DIR = os.path.dirname(__file__) + +# for quick rebuilds +""" +rm -rf /b/doc/python_api/sphinx-* && \ +./blender.bin --background -noaudio --factory-startup --python doc/python_api/sphinx_doc_gen.py && \ +sphinx-build doc/python_api/sphinx-in doc/python_api/sphinx-out +""" # Switch for quick testing -if 1: +if not SCRIPT_ARGS.test_build: # full build EXCLUDE_INFO_DOCS = False EXCLUDE_MODULES = () @@ -123,13 +166,19 @@ else: FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID") # allow FILTER_BPY_OPS = ("import.scene", ) # allow - # for quick rebuilds - """ -rm -rf /b/doc/python_api/sphinx-* && \ -./blender.bin --background -noaudio --factory-startup --python doc/python_api/sphinx_doc_gen.py && \ -sphinx-build doc/python_api/sphinx-in doc/python_api/sphinx-out +try: + __import__("aud") +except ImportError: + print("Warning: Built without 'aud' module, docs incomplete...") + EXCLUDE_MODULES = EXCLUDE_MODULES + ("aud", ) - """ +# examples +EXAMPLES_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "examples")) +EXAMPLE_SET = set() +EXAMPLE_SET_USED = set() + +#rst files dir +RST_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "rst")) # extra info, not api reference docs # stored in ./rst/info_* @@ -147,17 +196,9 @@ RNA_BLACKLIST = { "UserPreferencesSystem": {"language", }, } - # ----------------------------------------------------------------------------- # configure compile time options -try: - __import__("aud") -except ImportError: - print("Warning: Built without 'aud' module, docs incomplete...") - EXCLUDE_MODULES = EXCLUDE_MODULES + ("aud", ) - - # lame, python wont give some access ClassMethodDescriptorType = type(dict.__dict__['fromkeys']) MethodDescriptorType = type(dict.get) @@ -166,7 +207,6 @@ from types import MemberDescriptorType _BPY_STRUCT_FAKE = "bpy_struct" _BPY_PROP_COLLECTION_FAKE = "bpy_prop_collection" -_BPY_FULL_REBUILD = False if _BPY_PROP_COLLECTION_FAKE: _BPY_PROP_COLLECTION_ID = ":class:`%s`" % _BPY_PROP_COLLECTION_FAKE @@ -1442,51 +1482,19 @@ def rna2sphinx(BASEPATH): file.close() -def handle_args(): - ''' - get the args passed to blender after "--", all of which are ignored by blender - - we can give the path of sphinx-in after '--', using for example: - ./cmake/bin/blender -b -P ./blender/doc/python_api/sphinx_doc_gen.py -- ./python_api - ''' - - import argparse # to parse options for us and print a nice help message - - # When --help or no args are given, print the usage text - parser = argparse.ArgumentParser( - formatter_class=argparse.RawDescriptionHelpFormatter, - usage=script_help_msg) - - # output dir for apidocs - parser.add_argument("-o", "--output", - dest="output_dir", - type=str, - required=False, - help="Path of API docs directory (optional)") - - argv = [] - if "--" in sys.argv: - argv = sys.argv[sys.argv.index("--") + 1:] # get all args after "--" - - return parser.parse_args(argv) - - def main(): - - args = handle_args() - - # output dirs - if args.output_dir: - output_dir = args.output_dir - if not os.path.exists(args.output_dir): - os.mkdir(args.output_dir) + + # output dir + if SCRIPT_ARGS.output_dir: + output_dir = SCRIPT_ARGS.output_dir + if not os.path.exists(SCRIPT_ARGS.output_dir): + os.mkdir(SCRIPT_ARGS.output_dir) else: output_dir = SCRIPT_DIR + # sphinx dirs sphinx_in_dir = os.path.join(output_dir, "sphinx-in") sphinx_out_dir = os.path.join(output_dir, "sphinx-out") - - # only for partial updates sphinx_in_tmp_dir = sphinx_in_dir + "-tmp" if not os.path.exists(sphinx_in_dir): os.mkdir(sphinx_in_dir) @@ -1496,7 +1504,7 @@ def main(): EXAMPLE_SET.add(os.path.splitext(f)[0]) # only for full updates - if _BPY_FULL_REBUILD: + if SCRIPT_ARGS.full_rebuild: shutil.rmtree(sphinx_in_dir, True) shutil.rmtree(sphinx_out_dir, True) else: @@ -1505,7 +1513,7 @@ def main(): rna2sphinx(sphinx_in_tmp_dir) - if not _BPY_FULL_REBUILD: + if not SCRIPT_ARGS.full_rebuild: import filecmp # now move changed files from 'sphinx_in_tmp_dir' --> 'sphinx_in_dir' -- cgit v1.2.3