diff options
author | Campbell Barton <ideasman42@gmail.com> | 2011-02-16 20:31:04 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2011-02-16 20:31:04 +0300 |
commit | aed7eaf0d9171c4bfa7814e141afad773cb31441 (patch) | |
tree | dfe4af7d0ff2986a0768244f75a16888d1660c24 /doc/python_api/sphinx_doc_gen.py | |
parent | 6b12fa8fed341b7c14dbfb98c1895b7093cab0b7 (diff) |
sphinx doc gen: multiple examples possible and include the scripts docstring inline in sphinx.
also tag unused vars
Diffstat (limited to 'doc/python_api/sphinx_doc_gen.py')
-rw-r--r-- | doc/python_api/sphinx_doc_gen.py | 52 |
1 files changed, 50 insertions, 2 deletions
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index 565a6447cc8..38218675484 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -73,7 +73,7 @@ else: "mathutils.geometry", ) - FILTER_BPY_TYPES = ("Mesh", ) # allow + FILTER_BPY_TYPES = ("Operator", ) # allow FILTER_BPY_OPS = ("import_scene", ) # allow # for quick rebuilds @@ -131,14 +131,60 @@ def range_str(val): return str(val) +def example_extract_docstring(filepath): + file = open(filepath, 'r') + 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 + + 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)) + + # extract the comment + filepath = "../examples/%s.%s" % (example_id, ext) + filepath_full = os.path.join(os.path.dirname(fw.__self__.name), filepath) + + text, line_no = example_extract_docstring(filepath_full) + + for line in text.split("\n"): + fw("%s\n" % (ident + line).rstrip()) + fw("\n") + + fw("%s.. literalinclude:: %s\n" % (ident, filepath)) + fw("%s :lines: %d-\n" % (ident, line_no)) + fw("\n") EXAMPLE_SET_USED.add(example_id) else: if bpy.app.debug: print("\tskipping example:", example_id) + # 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 + def write_indented_lines(ident, fn, text, strip=True): ''' @@ -517,6 +563,8 @@ def pyrna2sphinx(BASEPATH): fw(".. module:: bpy.types\n\n") + write_example_ref("", fw, "bpy.types.%s" % struct.identifier) + base_ids = [base.identifier for base in struct.get_bases()] if _BPY_STRUCT_FAKE: |