css-related code updates and doc additions

Author: seanpue

doc/source/index.rst

@@ -285,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
 ---------------------

jupyter_sphinx/execute.py

@@ -134,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
@@ -596,6 +598,8 @@ 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'],
@@ -604,7 +608,6 @@ def attach_outputs(output_nodes, node, thebe_config, cm_language):
         thebe_source.children = [source]
 
         node.children = [thebe_source]
-        node.attributes["classes"] = ["jupyter_container"] # add jupyter classes even if thebe_config <-- CHECK
 
         if not node.attributes['hide_output']:
             thebe_output = ThebeOutputNode()
@@ -614,12 +617,8 @@ def attach_outputs(output_nodes, node, thebe_config, cm_language):
             else:
                 node.children = node.children + [thebe_output]
     else:
-        # Only add container class if code is shown
         if node.attributes['hide_code']:
             node.children = []
-        else:
-            node.attributes["classes"] = ["jupyter_container"]
-
         if not node.attributes['hide_output']:
             if node.attributes['code_below']:
                 node.children = output_nodes + node.children