From c1cd33e166fa0b0f9419ec9d8a19d124452019d3 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Sun, 28 Feb 2010 13:45:08 +0000 Subject: [PATCH] examples for autogenerated docs are now implicit and used when available. This means adding the file "bpy.props.py" in the examples dir will automatically be used when generating docs, unused examples give warnings. --- ...{mathutils_euler.py => Mathutils.Euler.py} | 0 ...athutils_matrix.py => Mathutils.Matrix.py} | 0 ...hutils_quat.py => Mathutils.Quaternion.py} | 0 ...athutils_vector.py => Mathutils.Vector.py} | 0 .../examples/{mathutils.py => Mathutils.py} | 0 source/blender/python/doc/sphinx_doc_gen.py | 31 +++++++++++++++++++ source/blender/python/generic/Mathutils.c | 4 +-- source/blender/python/generic/euler.c | 4 +-- source/blender/python/generic/matrix.c | 4 +-- source/blender/python/generic/quat.c | 4 +-- source/blender/python/generic/vector.c | 4 +-- 11 files changed, 36 insertions(+), 15 deletions(-) rename source/blender/python/doc/examples/{mathutils_euler.py => Mathutils.Euler.py} (100%) rename source/blender/python/doc/examples/{mathutils_matrix.py => Mathutils.Matrix.py} (100%) rename source/blender/python/doc/examples/{mathutils_quat.py => Mathutils.Quaternion.py} (100%) rename source/blender/python/doc/examples/{mathutils_vector.py => Mathutils.Vector.py} (100%) rename source/blender/python/doc/examples/{mathutils.py => Mathutils.py} (100%) diff --git a/source/blender/python/doc/examples/mathutils_euler.py b/source/blender/python/doc/examples/Mathutils.Euler.py similarity index 100% rename from source/blender/python/doc/examples/mathutils_euler.py rename to source/blender/python/doc/examples/Mathutils.Euler.py diff --git a/source/blender/python/doc/examples/mathutils_matrix.py b/source/blender/python/doc/examples/Mathutils.Matrix.py similarity index 100% rename from source/blender/python/doc/examples/mathutils_matrix.py rename to source/blender/python/doc/examples/Mathutils.Matrix.py diff --git a/source/blender/python/doc/examples/mathutils_quat.py b/source/blender/python/doc/examples/Mathutils.Quaternion.py similarity index 100% rename from source/blender/python/doc/examples/mathutils_quat.py rename to source/blender/python/doc/examples/Mathutils.Quaternion.py diff --git a/source/blender/python/doc/examples/mathutils_vector.py b/source/blender/python/doc/examples/Mathutils.Vector.py similarity index 100% rename from source/blender/python/doc/examples/mathutils_vector.py rename to source/blender/python/doc/examples/Mathutils.Vector.py diff --git a/source/blender/python/doc/examples/mathutils.py b/source/blender/python/doc/examples/Mathutils.py similarity index 100% rename from source/blender/python/doc/examples/mathutils.py rename to source/blender/python/doc/examples/Mathutils.py diff --git a/source/blender/python/doc/sphinx_doc_gen.py b/source/blender/python/doc/sphinx_doc_gen.py index bfe51eddf32..f2fc58c5653 100644 --- a/source/blender/python/doc/sphinx_doc_gen.py +++ b/source/blender/python/doc/sphinx_doc_gen.py @@ -43,6 +43,9 @@ import bpy import rna_info reload(rna_info) +EXAMPLE_SET = set() +EXAMPLE_SET_USED = set() + def range_str(val): if val < -10000000: return '-inf' if val > 10000000: return 'inf' @@ -51,6 +54,16 @@ def range_str(val): else: return str(val) + +def write_example_ref(ident, fw, example_id, ext=".py"): + if example_id in EXAMPLE_SET: + fw("%s.. literalinclude:: ../examples/%s%s\n\n" % (ident, example_id, ext)) + EXAMPLE_SET_USED.add(example_id) + else: + if bpy.app.debug: + print("\tskipping example:", example_id) + + def write_indented_lines(ident, fn, text, strip=True): if text is None: return @@ -152,6 +165,8 @@ def pymodule2sphinx(BASEPATH, module_name, module, title): # Note, may contain sphinx syntax, dont mangle! fw(module.__doc__.strip()) fw("\n\n") + + write_example_ref("", fw, module_name) # write members of the module # only tested with PyStructs which are not exactly modules @@ -188,6 +203,7 @@ def pymodule2sphinx(BASEPATH, module_name, module, title): if value.__doc__: write_indented_lines(" ", fw, value.__doc__, False) fw("\n") + write_example_ref(" ", fw, module_name + "." + attribute) for key in sorted(value.__dict__.keys()): if key.startswith("__"): @@ -197,6 +213,7 @@ def pymodule2sphinx(BASEPATH, module_name, module, title): if descr.__doc__: fw(" .. attribute:: %s\n\n" % key) write_indented_lines(" ", fw, descr.__doc__, False) + write_example_ref(" ", fw, module_name + "." + attribute + "." + key) fw("\n") for key in sorted(value.__dict__.keys()): @@ -206,6 +223,7 @@ def pymodule2sphinx(BASEPATH, module_name, module, title): if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet if descr.__doc__: write_indented_lines(" ", fw, descr.__doc__, False) + write_example_ref(" ", fw, module_name + "." + attribute + "." + key) fw("\n") fw("\n\n") @@ -501,14 +519,27 @@ if __name__ == '__main__': path_in = 'source/blender/python/doc/sphinx-in' path_out = 'source/blender/python/doc/sphinx-in' + path_examples = 'source/blender/python/doc/examples' shutil.rmtree(path_in, True) shutil.rmtree(path_out, True) + + for f in os.listdir(path_examples): + if f.endswith(".py"): + EXAMPLE_SET.add(os.path.splitext(f)[0]) + rna2sphinx(path_in) # for fast module testing # os.system("rm source/blender/python/doc/sphinx-in/bpy.types.*.rst") # os.system("rm source/blender/python/doc/sphinx-in/bpy.ops.*.rst") + + EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED + if EXAMPLE_SET_UNUSED: + print("\nUnused examples found in '%s'..." % path_examples) + for f in EXAMPLE_SET_UNUSED: + print(" %s.py" % f) + print(" %d total\n" % len(EXAMPLE_SET_UNUSED)) import sys sys.exit() diff --git a/source/blender/python/generic/Mathutils.c b/source/blender/python/generic/Mathutils.c index 0ded2b18264..8ad388ac540 100644 --- a/source/blender/python/generic/Mathutils.c +++ b/source/blender/python/generic/Mathutils.c @@ -55,9 +55,7 @@ //-------------------------DOC STRINGS --------------------------- static char M_Mathutils_doc[] = -"This module provides access to matrices, eulers, quaternions and vectors.\n" -"\n" -".. literalinclude:: ../examples/mathutils.py\n"; +"This module provides access to matrices, eulers, quaternions and vectors."; //-----------------------------METHODS---------------------------- //-----------------quat_rotation (internal)----------- diff --git a/source/blender/python/generic/euler.c b/source/blender/python/generic/euler.c index dcd6bcb031c..84360a76e61 100644 --- a/source/blender/python/generic/euler.c +++ b/source/blender/python/generic/euler.c @@ -564,9 +564,7 @@ static struct PyMethodDef Euler_methods[] = { //------------------PY_OBECT DEFINITION-------------------------- static char euler_doc[] = -"This object gives access to Eulers in Blender.\n" -"\n" -".. literalinclude:: ../examples/mathutils_euler.py\n"; +"This object gives access to Eulers in Blender."; PyTypeObject euler_Type = { PyVarObject_HEAD_INIT(NULL, 0) diff --git a/source/blender/python/generic/matrix.c b/source/blender/python/generic/matrix.c index 0b0b1470823..bd819128753 100644 --- a/source/blender/python/generic/matrix.c +++ b/source/blender/python/generic/matrix.c @@ -1335,9 +1335,7 @@ static struct PyMethodDef Matrix_methods[] = { /*------------------PY_OBECT DEFINITION--------------------------*/ static char matrix_doc[] = -"This object gives access to Matrices in Blender.\n" -"\n" -".. literalinclude:: ../examples/mathutils_matrix.py\n"; +"This object gives access to Matrices in Blender."; PyTypeObject matrix_Type = { PyVarObject_HEAD_INIT(NULL, 0) diff --git a/source/blender/python/generic/quat.c b/source/blender/python/generic/quat.c index b7cc45a7690..3a9617c05c4 100644 --- a/source/blender/python/generic/quat.c +++ b/source/blender/python/generic/quat.c @@ -844,9 +844,7 @@ static PyGetSetDef Quaternion_getseters[] = { //------------------PY_OBECT DEFINITION-------------------------- static char quaternion_doc[] = -"This object gives access to Quaternions in Blender.\n" -"\n" -".. literalinclude:: ../examples/mathutils_quat.py\n"; +"This object gives access to Quaternions in Blender."; PyTypeObject quaternion_Type = { PyVarObject_HEAD_INIT(NULL, 0) diff --git a/source/blender/python/generic/vector.c b/source/blender/python/generic/vector.c index d5ff44ae5ad..1e44ddafd37 100644 --- a/source/blender/python/generic/vector.c +++ b/source/blender/python/generic/vector.c @@ -2129,9 +2129,7 @@ static struct PyMethodDef Vector_methods[] = { */ static char vector_doc[] = -"This object gives access to Vectors in Blender.\n" -"\n" -".. literalinclude:: ../examples/mathutils_vector.py\n"; +"This object gives access to Vectors in Blender."; PyTypeObject vector_Type = { PyVarObject_HEAD_INIT(NULL, 0)