merged upstream

Author: seanpue

doc/source/index.rst

@@ -250,11 +250,6 @@ produces:
 
     print("hello, world!", file=sys.stderr)
 
-.. warning::
-
-    Note that output written to ``stderr`` is not displayed any differently than output written
-    to ``stdout``.
-
 Controlling the execution environment
 -------------------------------------
 The execution environment can be controlled by using the ``jupyter-kernel`` directive. This directive takes
@@ -289,6 +284,30 @@ the code. If a document contains ``jupyter-kernel`` directives with ``:id:`` spe
 the name provided to ``:id:`` can be used to get the code for the cells belonging to the
 that Jupyter session.
 
+Styling options
+---------------
+
+The CSS (Cascading Style Sheet) class structure of jupyter-sphinx is the
+following::
+
+  - jupyter_container
+    - code_cell
+    - stderr
+    - output
+
+If a code cell is not displayed, the output is provided without the
+``jupyter_container``. If you want to adjust the styles, add a new stylesheet,
+e.g. ``custom.css``, and adjust your ``conf.py`` to load it. How you do so depends on
+the theme you are using.
+
+Here is a sample ``custom.css`` file overriding the ``stderr`` background color:
+
+.. code-block:: css
+
+  .jupyter_container .stderr {
+      background-color: #7FFF00;
+  }
+
 
 Configuration options
 ---------------------

jupyter_sphinx/css/jupyter-sphinx.css

@@ -0,0 +1,108 @@
+/* Stylesheet for jupyter-sphinx
+
+These styles mimic the Jupyter HTML styles.
+
+The default CSS (Cascading Style Sheet) class structure of jupyter-sphinx
+is the following:
+
+jupyter_container
+  code_cell (optional)
+  stderr (optional)
+  output (optional)
+
+If the code_cell is not displayed, then there is not a jupyter_container, and
+the output is provided without CSS.
+
+This stylesheet attempts to override the defaults of all packaged Sphinx themes
+to display jupter-sphinx cells in a Jupyter-like style.
+
+If you want to adjust the styles, add additional custom CSS to override these
+styles.
+
+After a build, this stylesheet is loaded from ./_static/jupyter-sphinx.css .
+
+*/
+
+
+div.jupyter_container {
+    padding: .4em;
+    margin: 0 0 .4em 0;
+    background-color: #FFFF;
+    border: 1px solid #CCC;
+    -moz-box-shadow: 2px 2px 4px rgba(87, 87, 87, 0.2);
+    -webkit-box-shadow: 2px 2px 4px rgba(87, 87, 87, 0.2);
+    box-shadow: 2px 2px 4px rgba(87, 87, 87, 0.2);
+}
+.jupyter_container div.code_cell {
+  border: 1px solid #cfcfcf;
+  border-radius: 2px;
+  background-color: #f7f7f7;
+  margin: 0 0;
+}
+
+.jupyter_container div.code_cell pre {
+  padding: 4px;
+  margin: 0 0;
+  background-color: #f7f7f7;
+  border: none;
+  background: none;
+  -webkit-box-shadow: none; /* for nature */
+  -moz-box-shadow: none; /* for nature */
+}
+
+.jupyter_container div.code_cell * {
+  margin: 0 0;
+}
+div.jupyter_container div.highlight {
+  background-color: #f7f7f7; /* for haiku */
+}
+div.jupyter_container * {
+    padding: 0;
+    margin: 0;
+}
+/* overrides for sphinx_rtd_theme */
+.rst-content .jupyter_container div[class^='highlight'],
+.document .jupyter_container div[class^='highlight'],
+.rst-content .jupyter_container pre.literal-block {
+  border:none;
+  margin: 0;
+  padding: 0;
+  background: none;
+  padding: 3px;
+  background-color: transparent;
+}
+/* restore Mathjax CSS, as it assumes a vertical margin. */
+.jupyter_container .MathJax_Display {
+  margin: 1em 0em;
+  text-align: center;
+}
+.jupyter_container .stderr {
+    background-color: #FCC;
+    border: none;
+    padding: 3px;
+}
+.jupyter_container .output {
+    border: none;
+}
+.jupyter_container div.output pre {
+    background-color: white;
+    background: none;
+    padding: 4px;
+    border: none;
+    -webkit-box-shadow: none; /* for nature */
+    -moz-box-shadow: none; /* for nature */
+}
+.jupyter_container .code_cell td.linenos {
+  align: right;
+  padding: 4px 4px 4px 8px;
+  border-right: 1px solid #cfcfcf;
+  color: #999;
+}
+.jupyter_container .output .highlight {
+  background-color: #ffffff;
+}
+/* combine sequential jupyter cells,
+   by moving sequential ones up higher on y-axis */
+div.jupyter_container + div.jupyter_container {
+    margin: -.5em 0 .4em 0; 
+}

jupyter_sphinx/execute.py

@@ -55,11 +55,14 @@ def builder_inited(app):
     if embed_url:
         app.add_js_file(embed_url)
 
+    # add jupyter-sphinx css
+    app.add_css_file('jupyter-sphinx.css')
     # Check if a thebelab config was specified
     if app.config.jupyter_sphinx_thebelab_config:
         app.add_js_file('thebelab-helper.js')
         app.add_css_file('thebelab.css')
 
+
 ### Directives and their associated doctree nodes
 
 class JupyterKernel(Directive):
@@ -411,6 +414,12 @@ def apply(self):
                     source["highlight_args"] = {'linenostart': linenostart}
                     linenostart += source.rawsource.count("\n") + 1
 
+
+            # Add code cell CSS class
+            for node in nodes:
+                source = node.children[0]
+                source.attributes["classes"] = ["code_cell"]
+
             # Write certain cell outputs (e.g. images) to separate files, and
             # modify the metadata of the associated cells in 'notebook' to
             # include the path to the output file.
@@ -505,13 +514,34 @@ 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.
+                    #
+                    # Not setting "rawsource" disables Pygment hightlighting, which
+                    # would otherwise add a <div class="highlight">.
+
+                    container = docutils.nodes.container(classes=["stderr"])
+                    container.append(docutils.nodes.literal_block(
+                            text=output['text'],
+                            rawsource='',  # disables Pygment highlighting
+                            language='none',
+                            classes=["stderr"]
+                    ))
+                    to_add.append(container)
+            else:
+                to_add.append(docutils.nodes.literal_block(
+                    text=output['text'],
+                    rawsource=output['text'],
+                    language='none',
+                    classes=["output", "stream"]
+                ))
         elif (
             output_type == 'error'
         ):
@@ -521,6 +551,7 @@ def cell_output_to_nodes(cell, data_priority, write_stderr, dir, thebe_config):
                 text=text,
                 rawsource=text,
                 language='ipythontb',
+                classes =["output", "traceback"]
             ))
         elif (
             output_type in ('display_data', 'execute_result')
@@ -545,19 +576,23 @@ def cell_output_to_nodes(cell, data_priority, write_stderr, dir, thebe_config):
             elif mime_type == 'text/html':
                 to_add.append(docutils.nodes.raw(
                     text=data,
-                    format='html'
+                    format='html',
+                    classes=["output", "text_html"]
+
                 ))
             elif mime_type == 'text/latex':
                 to_add.append(math_block(
                     text=data,
                     nowrap=False,
                     number=None,
+                    classes=["output", "text_latex"]
                  ))
             elif mime_type == 'text/plain':
                 to_add.append(docutils.nodes.literal_block(
                     text=data,
                     rawsource=data,
                     language='none',
+                    classes=["output", "text_plain"]
                 ))
             elif mime_type == 'application/javascript':
                 to_add.append(docutils.nodes.raw(
@@ -572,9 +607,10 @@ def cell_output_to_nodes(cell, data_priority, write_stderr, dir, thebe_config):
 
 
 def attach_outputs(output_nodes, node, thebe_config, cm_language):
+    if not node.attributes["hide_code"]:  # only add css if code is displayed
+        node.attributes["classes"] = ["jupyter_container"]
     if thebe_config:
         source = node.children[0]
-
         thebe_source = ThebeSourceNode(hide_code=node.attributes['hide_code'],
                                        code_below=node.attributes['code_below'],
                                        language=cm_language)
@@ -592,7 +628,6 @@ def attach_outputs(output_nodes, node, thebe_config, cm_language):
     else:
         if node.attributes['hide_code']:
             node.children = []
-
         if not node.attributes['hide_output']:
             if node.attributes['code_below']:
                 node.children = output_nodes + node.children
@@ -742,6 +777,11 @@ def build_finished(app, env):
     if app.builder.format != 'html':
         return
 
+    # Copy stylesheet
+    src = os.path.join(os.path.dirname(__file__), 'css')
+    dst = os.path.join(app.outdir, '_static')
+    copy_asset(src, dst)
+
     thebe_config = app.config.jupyter_sphinx_thebelab_config
     if not thebe_config:
         return
@@ -754,6 +794,7 @@ def build_finished(app, env):
 
 def setup(app):
     # Configuration
+
     app.add_config_value(
         'jupyter_execute_kwargs',
         dict(timeout=-1, allow_errors=True, store_widget_state=True),

setup.py

@@ -30,5 +30,5 @@
         'nbformat',
     ],
     python_requires = '>= 3.5',
-    package_data={'jupyter_sphinx': ['thebelab/*']},
+    package_data={'jupyter_sphinx': ['thebelab/*', 'css/*']},
 )

tests/test_execute.py

@@ -310,7 +310,8 @@ 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 cell.children[1].astext().strip() == "hello world"
 
 
 thebe_config = "jupyter_sphinx_thebelab_config = {\"dummy\": True}"