Added options for removing tags from rst file

CHANGELOG.rst

@@ -1,3 +1,28 @@
+v0.3.0
+======
+Added
+-----
+* The removal of tags for the converted rst file. With
+  `nbconvert 5.3 <https://nbconvert.readthedocs.io/en/stable/changelog.html>`__
+  we have the ``nbconvert.preprocessors.TagRemovePreprocessor`` available
+  which gave the motivation to 4 new gallery configuration values, namely
+
+  remove_all_outputs_tags: set
+      Tags indicating cells for which the outputs are to be removed,
+      matches tags in cell.metadata.tags.
+  remove_cell_tags: set
+      Tags indicating which cells are to be removed, matches tags in
+      cell.metadata.tags.
+  remove_input_tags: set
+      Tags indicating cells for which input is to be removed,
+      matches tags in cell.metadata.tags.
+  remove_single_output_tags: set
+      Tags indicating which individual outputs are to be removed, matches
+      output i tags in cell.outputs[i].metadata.tags.
+
+  The tags specified by these configuration values will be removed in the
+  rst file.
+
 v0.2.2
 ======
 Added
@@ -29,4 +54,3 @@ Changed
 * The name of a thumbnail is now ``reference + '_thumb.png'`` where
   ``reference`` is the section label of the rst file
 * Reference labels are now all lower case
-

docs/conf.py

@@ -406,6 +406,7 @@
     'sphinx_nbexamples_doc': (
         'http://sphinx-nbexamples.readthedocs.io/en/latest/', None),
     'psyplot': ('http://psyplot.readthedocs.io/en/latest/', None),
+    'nbconvert': ('https://nbconvert.readthedocs.io/en/latest/', None),
 }
 if six.PY3:
     intersphinx_mapping['python'] = ('https://docs.python.org/3.4/', None)

docs/getting_started.rst

@@ -1,3 +1,5 @@
+.. currentmodule:: sphinx_nbexamples
+
 .. getting_started:
 
 Getting started
@@ -146,3 +148,27 @@ keyword, too.
     provide it by yourself (see :ref:`thumbnails`).
 
 .. _readthedocs.org: http://readthedocs.org
+
+.. _tag-removal:
+
+Removing cells
+--------------
+Using notebook 5.0 and nbconvert 5.3 and higher, you can also tag cells
+and specify them for removal in the converted rst file.
+
+In the jupyter notebook click on
+:menuselection:`View --> Cell Toolbar --> Tags` and assign a tag to the cell
+you want to remove. You can then use one or more of the keywords
+
+remove_all_outputs_tags
+    removes all outputs
+remove_cell_tags
+    removes the entire cell
+remove_input_tags
+    removes the input and only keeps the output
+remove_single_output_tags
+    Removes an individual output
+
+in the :confval:`example_gallery_config`. See the :class:`Gallery`
+and :class:`nbconvert.preprocessors.Preprocessor` documentation for more
+information.

requirements.txt

@@ -1,13 +1,12 @@
 # nbconvert
 #   https://nbconvert.readthedocs.io/en/latest/changelog.html
-nbconvert==5.2.1 # rg.filter: >= 4.2, <5.3
+nbconvert==5.3.1 # rq.filter: >= 4.2, <5.4
 
 
 # notebook
 #   https://jupyter-notebook.readthedocs.io/en/latest/changelog.html
-notebook==4.3.2 # rq.filter: >=4.2, <4.4
+notebook==5.1.0 # rq.filter: >=4.2, <5.2
 
 # Sphinx
 #   http://www.sphinx-doc.org/en/stable/changes.html
 sphinx==1.6.3 # rq.filter: >=1.3, <1.7
-

setup.py

@@ -11,7 +11,7 @@ def readme():
 
 
 setup(name='sphinx-nbexamples',
-      version='0.2.2',
+      version='0.3.0',
       description=(
           'Create an examples gallery with sphinx from Jupyter Notebooks'),
       long_description=readme(),

sphinx_nbexamples/__init__.py

@@ -25,6 +25,7 @@
 import nbconvert
 import nbformat
 from shutil import copyfile
+from copy import deepcopy
 import logging
 import subprocess as spr
 from docutils.parsers.rst import Directive
@@ -45,7 +46,7 @@
         from ordereddict import OrderedDict
 
 
-__version__ = '0.2.2'
+__version__ = '0.3.0'
 
 __author__ = "Philipp Sommer"
 
@@ -240,11 +241,15 @@ def url(self):
         if url is not None:
             return nbviewer_link(url)
 
+    @property
+    def remove_tags(self):
+        return any(self.tag_options.values())
+
     def __init__(self, infile, outfile, disable_warnings=True,
                  preprocess=True, clear=True, code_example=None,
                  supplementary_files=None, other_supplementary_files=None,
                  thumbnail_figure=None, url=None, insert_bokeh=False,
-                 insert_bokeh_widgets=False):
+                 insert_bokeh_widgets=False, tag_options={}):
         """
         Parameters
         ----------
@@ -277,7 +282,10 @@ def __init__(self, infile, outfile, disable_warnings=True,
         insert_bokeh: False or str
             The version string for bokeh to use for the style sheet
         insert_bokeh_widgets: bool or str
-            The version string for bokeh to use for the widgets style sheet"""
+            The version string for bokeh to use for the widgets style sheet
+        tag_options: dict
+            A dictionary with traitlets for the
+            :class:`nbconvert.preprocessors.TagRemovePreprocessor`"""
         self.infile = infile
         self.outfile = outfile
         self.preprocess = preprocess
@@ -289,6 +297,7 @@ def __init__(self, infile, outfile, disable_warnings=True,
         self._url = url
         self.insert_bokeh = insert_bokeh
         self.insert_bokeh_widgets = insert_bokeh_widgets
+        self.tag_options = tag_options
         self.process_notebook(disable_warnings)
         self.create_thumb()
 
@@ -343,7 +352,16 @@ def process_notebook(self, disable_warnings=True):
 
         self.py_file = self.get_out_file('py')
 
-        self.create_rst(nb, in_dir, odir)
+        if self.remove_tags:
+            tp = nbconvert.preprocessors.TagRemovePreprocessor(timeout=300)
+            for key, val in self.tag_options.items():
+                setattr(tp, key, set(val))
+            nb4rst = deepcopy(nb)
+            tp.preprocess(nb4rst, {'metadata': {'path': in_dir}})
+        else:
+            nb4rst = nb
+
+        self.create_rst(nb4rst, in_dir, odir)
 
         if self.clear:
             cp.preprocess(nb, {'metadata': {'path': in_dir}})
@@ -610,7 +628,9 @@ def __init__(self, examples_dirs=['../examples'], gallery_dirs=None,
                  dont_preprocess=[], preprocess=True, clear=True,
                  dont_clear=[], code_examples={}, supplementary_files={},
                  other_supplementary_files={}, thumbnail_figures={},
-                 urls=None, insert_bokeh=False, insert_bokeh_widgets=False):
+                 urls=None, insert_bokeh=False, insert_bokeh_widgets=False,
+                 remove_all_outputs_tags=set(), remove_cell_tags=set(),
+                 remove_input_tags=set(), remove_single_output_tags=set()):
         """
         Parameters
         ----------
@@ -675,6 +695,18 @@ def __init__(self, examples_dirs=['../examples'], gallery_dirs=None,
         insert_bokeh_widgets: bool or str
             If True, the bokeh widget js [3]_ is inserted in the notebooks that
             have bokeh loaded (using the installed or specified bokeh version)
+        remove_all_outputs_tags: set
+            Tags indicating cells for which the outputs are to be removed,
+            matches tags in cell.metadata.tags.
+        remove_cell_tags: set
+            Tags indicating which cells are to be removed, matches tags in
+            cell.metadata.tags.
+        remove_input_tags: set
+            Tags indicating cells for which input is to be removed,
+            matches tags in cell.metadata.tags.
+        remove_single_output_tags: set
+            Tags indicating which individual outputs are to be removed, matches
+            output i tags in cell.outputs[i].metadata.tags.
 
         References
         ----------
@@ -721,8 +753,14 @@ def __init__(self, examples_dirs=['../examples'], gallery_dirs=None,
         if insert_bokeh_widgets and not isstring(insert_bokeh_widgets):
             import bokeh
             insert_bokeh_widgets = bokeh.__version__
+        tag_options = {
+            'remove_all_outputs_tags': remove_all_outputs_tags,
+            'remove_cell_tags': remove_cell_tags,
+            'remove_input_tags': remove_input_tags,
+            'remove_single_output_tags': remove_single_output_tags}
         self._nbp_kws = {'insert_bokeh': insert_bokeh,
-                         'insert_bokeh_widgets': insert_bokeh_widgets}
+                         'insert_bokeh_widgets': insert_bokeh_widgets,
+                         'tag_options': tag_options}
 
     def process_directories(self):
         """Create the rst files from the input directories in the

tests/sphinx_supp_py2/raw_examples/example_tag_removal.ipynb

@@ -0,0 +1,55 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Example for testing the removal of cells\n",
+    "This example includes a cell that should be removed"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {
+    "tags": [
+     "remove_in_docs"
+    ]
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "This should be removed!\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(\"This should be removed!\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "celltoolbar": "Tags",
+  "kernelspec": {
+   "display_name": "Python 2",
+   "language": "python",
+   "name": "python2"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "3.5.0rc4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

tests/sphinx_supp_py3/conf.py

@@ -20,7 +20,8 @@
                  'example_mpl_test_figure_chosen.ipynb'): 0},
     'supplementary_files': {
         osp.join(dirname, 'raw_examples',
-                 'example_hello_world.ipynb'): ['test2.txt']}}
+                 'example_hello_world.ipynb'): ['test2.txt']},
+    'remove_cell_tags': ['remove_in_docs']}
 
 exclude_patterns = ['raw_examples']
 

tests/sphinx_supp_py3/raw_examples/example_tag_removal.ipynb

@@ -0,0 +1,55 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Example for testing the removal of cells\n",
+    "This example includes a cell that should be removed"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {
+    "tags": [
+     "remove_in_docs"
+    ]
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "This should be removed!\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(\"This should be removed!\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "celltoolbar": "Tags",
+  "kernelspec": {
+   "display_name": "python3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.6.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

tests/test_sphinx_nbexamples.py

@@ -127,6 +127,16 @@ def test_magics(self):
             re.search(r'(?<!print\(.)Something %magic like.+(?!\))', rst),
             msg="Print output '%%magic like' not found in \n%s!" % rst)
 
+    def test_tag_removal(self):
+        """Test whether the tagged cell has been removed correctly"""
+        base = 'example_tag_removal'
+        rst_path = osp.join(self.src_dir, 'examples', base) + '.rst'
+        py_path = osp.join(self.src_dir, 'examples', base) + '.py'
+        with open(rst_path) as f:
+            self.assertNotIn('This should be removed!', f.read())
+        with open(py_path) as f:
+            self.assertIn('This should be removed!', f.read())
+
     def test_supplementary_files(self):
         """Test whether the supplementary files are inserted corretly"""
         rst_copy = osp.join(self.src_dir, 'examples', 'sub', 'test.txt')