Merge pull request #86 from seanpue/std_err_in_div

style stderr differently to stdout

Also allows for custom styling to be added to stderr with the 'stderr' CSS class.

Closes #71.

Author: jbweston

doc/source/_static/custom.css

@@ -0,0 +1,7 @@
+/*
+Custom CSS for stderr stream output.
+*/
+
+.stderr {
+    background-color: #FCC;
+}

doc/source/conf.py

@@ -41,3 +41,4 @@
         "repo": "jupyter/jupyter-sphinx",
     },
 }
+html_static_path = ["_static/custom.css"]  # css overrides for Alabaster theme

doc/source/index.rst

@@ -251,10 +251,12 @@ produces:
 
     print("hello, world!", file=sys.stderr)
 
-.. warning::
+.. note::
+  To adjust the CSS of the ``stderr`` stream, use the ``stderr`` class. If you are using
+  the default Sphinx theme, for example, add the following
+  `custom CSS <https://alabaster.readthedocs.io/en/latest/customization.html#custom-stylesheet>`_:
+    ``.stderr {background-color: #FCC}``
 
-    Note that output written to ``stderr`` is not displayed any differently than output written
-    to ``stdout``.
 
 Controlling the execution environment
 -------------------------------------

jupyter_sphinx/execute.py

@@ -494,13 +494,37 @@ def cell_output_to_nodes(cell, data_priority, write_stderr, dir, thebe_config):
         if (
             output_type == 'stream'
         ):
-            if not write_stderr and output["name"] == "stderr":
-                continue
-            to_add.append(docutils.nodes.literal_block(
-                text=output['text'],
-                rawsource=output['text'],
-                language='none',
-            ))
+            if output["name"] == "stderr":
+                if not write_stderr:
+                    continue
+                else:
+                    # Output a container with an unhighlighted literal block for
+                    # `stderr` messages.
+                    #
+                    # Adds a "stderr" class that can be customized by the user for both
+                    # the container and the literal_block.
+                    #
+                    # Also adds "error" as a base class, which is a fairly common
+                    # class in Sphinx themes. It should result in differentiation
+                    # from stdout in most Sphinx themes.
+                    #
+                    # Not setting "rawsource" disables Pygment hightlighting, which
+                    # would otherwise add a <div class="highlight">.
+
+                    container = docutils.nodes.container(classes=["error", "stderr"])
+                    container.append(docutils.nodes.literal_block(
+                            text=output['text'],
+                            rawsource='',  # disables Pygment highlighting
+                            language='none',
+                            classes=["error", "stderr"]
+                    ))
+                    to_add.append(container)
+            else:
+                to_add.append(docutils.nodes.literal_block(
+                    text=output['text'],
+                    rawsource=output['text'],
+                    language='none',
+                ))
         elif (
             output_type == 'error'
         ):

tests/test_execute.py

@@ -267,7 +267,9 @@ def test_stderr(doctree):
     tree = doctree(source)
     cell, = tree.traverse(JupyterCellNode)
     assert len(cell.children) == 2
-    assert cell.children[1].rawsource.strip() == "hello world"
+    assert 'stderr' in cell.children[1].attributes['classes']
+    assert 'error' in cell.children[1].attributes['classes']
+    assert cell.children[1].astext().strip() == "hello world"
 
 
 thebe_config = "jupyter_sphinx_thebelab_config = {\"dummy\": True}"