feat: emit empty warning only if no warnings exist

This is a bit more gymnastics than I think is warranted,
but wanted to play out the example.

Needing to inspect the stream proved more complex than
originally expected, as each version confroms to a slightly
different interface.

- Updated the outpout string to be clearer
- Added test for empty RST file

Signed-off-by: Mike Fiedler <[email protected]>

Author: miketheman

readme_renderer/rst.py

@@ -14,7 +14,7 @@
 from __future__ import absolute_import, division, print_function
 
 import io
-from typing import Any, Dict, IO, Optional, Union
+from typing import Any, Dict, Optional, TextIO, Union, TYPE_CHECKING
 
 from docutils.core import publish_parts
 from docutils.nodes import colspec, image
@@ -23,6 +23,10 @@
 
 from .clean import clean
 
+if TYPE_CHECKING:
+    # Prevent a circular import
+    from .integration.distutils import _WarningStream
+
 
 class ReadMeHTMLTranslator(HTMLTranslator):  # type: ignore[misc] # docutils is incomplete, returns `Any` python/typeshed#7256 # noqa E501
 
@@ -105,7 +109,7 @@ def emptytag(
 
 def render(
     raw: str,
-    stream: Optional[IO[str]] = None,
+    stream: Optional[Union[io.StringIO, TextIO, "_WarningStream"]] = None,
     **kwargs: Any
 ) -> Optional[str]:
     if stream is None:
@@ -129,5 +133,17 @@ def render(
     if rendered:
         return clean(rendered)
     else:
-        stream.write("no output rendered")
+        # If the warnings stream is empty, docutils had none, so add ours.
+
+        # We have to currently handle the legacy disutils integration check
+        # command, as it implements its own warnings stream structure.
+        # Once that code is removed, we can remove this conditional.
+        if hasattr(stream, "output"):
+            if not stream.output.getvalue():  # type: ignore[union-attr]
+                stream.write("No content rendered from RST source.")
+        elif isinstance(stream, io.StringIO) and not stream.getvalue():
+            stream.write("No content rendered from RST source.")
+        elif isinstance(stream, TextIO) and not stream.readlines():
+            # This is `sys.stderr` from using readme_renderer CLI
+            stream.write("No content rendered from RST source.")
         return None

tests/test_rst.py

@@ -55,11 +55,31 @@ def test_rst_raw():
     assert '"raw" directive disabled' in warnings.getvalue()
 
 
+def test_rst_empty_file():
+    warnings = io.StringIO()
+    assert render("", stream=warnings) is None
+
+    assert "No content rendered from RST source." in warnings.getvalue()
+
+
 def test_rst_header_only():
     warnings = io.StringIO()
     assert render("""
 Header
 ======
 """, stream=warnings) is None
 
-    assert "no output rendered" in warnings.getvalue()
+    assert "No content rendered from RST source." in warnings.getvalue()
+
+
+def test_header_and_malformed_emits_docutils_warning_only():
+    warnings = io.StringIO()
+    assert render("""
+Header
+======
+
+======
+""", stream=warnings) is None
+
+    assert len(warnings.getvalue().splitlines()) == 1
+    assert "No content rendered from RST source." not in warnings.getvalue()