Merge pull request #87 from seanpue/std_err_in_div

added css insertion to improve display

Author: akhmerov

doc/source/_static/custom.css

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

doc/source/conf.py

@@ -251,13 +251,6 @@ produces:
 
     print("hello, world!", file=sys.stderr)
 
-.. 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}``
-
-
 Controlling the execution environment
 -------------------------------------
 The execution environment can be controlled by using the ``jupyter-kernel`` directive. This directive takes
@@ -292,6 +285,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
 ---------------------

doc/source/index.rst

@@ -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/css/jupyter-sphinx.css

@@ -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):
@@ -131,6 +134,8 @@ class JupyterCell(Directive):
         If provided, the cell output will not be displayed in the output.
     code-below : bool
         If provided, the code will be shown below the cell output.
+    linenos : bool
+        If provided, the code will be shown with line numbers.
     raises : comma separated list of exception types
         If provided, a comma-separated list of exception type names that
         the cell may raise. If one of the listed execption types is raised
@@ -400,6 +405,12 @@ def apply(self):
                     source = node.children[0]
                     source["linenos"] = True
 
+
+            # 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.
@@ -504,26 +515,23 @@ def cell_output_to_nodes(cell, data_priority, write_stderr, dir, thebe_config):
                     # 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 = docutils.nodes.container(classes=["stderr"])
                     container.append(docutils.nodes.literal_block(
                             text=output['text'],
                             rawsource='',  # disables Pygment highlighting
                             language='none',
-                            classes=["error", "stderr"]
+                            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'
@@ -534,6 +542,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')
@@ -558,19 +567,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(
@@ -585,9 +598,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)
@@ -605,7 +619,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
@@ -755,6 +768,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
@@ -767,6 +785,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),

jupyter_sphinx/execute.py

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

setup.py

@@ -268,7 +268,6 @@ def test_stderr(doctree):
     cell, = tree.traverse(JupyterCellNode)
     assert len(cell.children) == 2
     assert 'stderr' in cell.children[1].attributes['classes']
-    assert 'error' in cell.children[1].attributes['classes']
     assert cell.children[1].astext().strip() == "hello world"