diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-03-31 09:44:16 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-03-31 09:47:31 +0300 |
commit | 43369ca80e62aa80b951823d1c78abef58852014 (patch) | |
tree | 20a8309ef61a33aa046fe1c62ca75ca5d644425b /doc | |
parent | d5f2043ab312470db38bd75762169807e9b3d84c (diff) |
PyDoc: quiet warning with literalinclude including blank lines
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.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/python_api/sphinx_doc_gen.py | 18 |
1 files changed, 11 insertions, 7 deletions
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index e71f3b2c303..8be194a58a2 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -553,7 +553,7 @@ def example_extract_docstring(filepath): line_no += 1 else: file.close() - return "", 0 + return "", 0, False for line in file: line_no += 1 @@ -563,15 +563,17 @@ def example_extract_docstring(filepath): text.append(line.rstrip()) line_no += 1 + line_no_has_content = False # Skip over blank lines so the Python code doesn't have blank lines at the top. for line in file: if line.strip(): + line_no_has_content = True break line_no += 1 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): @@ -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_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"): fw("%s\n" % (ident + line).rstrip()) fw("\n") - fw("%s.. literalinclude:: %s\n" % (ident, filepath)) - if line_no > 0: - fw("%s :lines: %d-\n" % (ident, line_no)) - fw("\n") + # Some files only contain a doc-string. + if line_no_has_content: + fw("%s.. literalinclude:: %s\n" % (ident, filepath)) + if line_no > 0: + fw("%s :lines: %d-\n" % (ident, line_no)) + fw("\n") EXAMPLE_SET_USED.add(example_id) else: if bpy.app.debug: |