[Bf-blender-cvs] [43369ca80e6] master: PyDoc: quiet warning with literalinclude including blank lines

[Campbell Barton]

Commit: 43369ca80e62aa80b951823d1c78abef58852014
Author: Campbell Barton
Date:   Wed Mar 31 17:44:16 2021 +1100
Branches: master
https://developer.blender.org/rB43369ca80e62aa80b951823d1c78abef58852014

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.

===================================================================

M	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 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: