archive/blender-archive
Archived
1
1
Fork 0
Code Pull Requests Packages Activity

PyDoc: quiet warning with literalinclude including blank lines

Browse Source 
Files that only contain a doc-string still included the last blank line,
since this normally contains code examples.

There are some cases where only a docstring exists
which made sphinx report warnings.
This commit is contained in:
Campbell Barton
2021-03-31 17:44:16 +11:00
parent d5f2043ab3
commit 43369ca80e
1 changed files with 11 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
doc/python_api/sphinx_doc_gen.py
View File

@@ -553,7 +553,7 @@ def example_extract_docstring(filepath):
line_no += 1 line_no += 1
else: else:
file.close() file.close()
return "", 0 return "", 0, False
for line in file: for line in file:
line_no += 1 line_no += 1
@@ -563,15 +563,17 @@ def example_extract_docstring(filepath):
text.append(line.rstrip()) text.append(line.rstrip())
line_no += 1 line_no += 1
line_no_has_content = False
# Skip over blank lines so the Python code doesn't have blank lines at the top. # Skip over blank lines so the Python code doesn't have blank lines at the top.
for line in file: for line in file:
if line.strip(): if line.strip():
line_no_has_content = True
break break
line_no += 1 line_no += 1
file.close() file.close()
return "\n".join(text), line_no return "\n".join(text), line_no, line_no_has_content
def title_string(text, heading_char, double=False): def title_string(text, heading_char, double=False):
@@ -590,16 +592,18 @@ def write_example_ref(ident, fw, example_id, ext="py"):
filepath = os.path.join("..", "examples", "%s.%s" % (example_id, ext)) filepath = os.path.join("..", "examples", "%s.%s" % (example_id, ext))
filepath_full = os.path.join(os.path.dirname(fw.__self__.name), filepath) filepath_full = os.path.join(os.path.dirname(fw.__self__.name), filepath)
text, line_no = example_extract_docstring(filepath_full) text, line_no, line_no_has_content = example_extract_docstring(filepath_full)
for line in text.split("\n"): for line in text.split("\n"):
fw("%s\n" % (ident + line).rstrip()) fw("%s\n" % (ident + line).rstrip())
fw("\n") fw("\n")
fw("%s.. literalinclude:: %s\n" % (ident, filepath)) # Some files only contain a doc-string.
if line_no > 0: if line_no_has_content:
fw("%s :lines: %d-\n" % (ident, line_no)) fw("%s.. literalinclude:: %s\n" % (ident, filepath))
fw("\n") if line_no > 0:
fw("%s :lines: %d-\n" % (ident, line_no))
fw("\n")
EXAMPLE_SET_USED.add(example_id) EXAMPLE_SET_USED.add(example_id)
else: else:
if bpy.app.debug: if bpy.app.debug: