From 37c886f67a20cfe15f9610ece1ef60e977d473a7 Mon Sep 17 00:00:00 2001 From: Matthias Geier Date: Sun, 6 Mar 2016 17:06:06 +0100 Subject: [PATCH] Add option nbsphinx_allow_errors --- doc/allow-errors.ipynb | 16 ++++++++++++---- doc/conf.py | 3 +++ doc/pre-executed.ipynb | 4 ++-- nbsphinx.py | 11 ++++++++--- 4 files changed, 25 insertions(+), 9 deletions(-) diff --git a/doc/allow-errors.ipynb b/doc/allow-errors.ipynb index b584f92a..cef4ed3f 100644 --- a/doc/allow-errors.ipynb +++ b/doc/allow-errors.ipynb @@ -17,17 +17,25 @@ "\n", "Normally, if an exception is raised while executing a notebook, the Sphinx build process is stopped immediately.\n", "\n", - "If a notebook contains errors on purpose (or if you are too lazy to fix them now), you can add this to the notebook's JSON metadata:\n", + "If a notebook contains errors on purpose (or if you are too lazy to fix them now), you have three options:\n", "\n", + "1. Manually execute the notebook in question and save the results, see [the pre-executed example notebook](pre-executed.ipynb#Exceptions).\n", + "\n", + "2. Allow errors in all notebooks by setting this option in [conf.py](conf.py):\n", + "```\n", + "nbsphinx_allow_errors = True\n", + "```\n", + "\n", + "3. Allow errors on a per-notebook basis by adding this to the notebook's JSON metadata:\n", "```json\n", "\"nbsphinx\": {\n", " \"allow_errors\": true\n", "},\n", "```\n", "\n", - "This very notebook is an example for this behavior.\n", + "This very notebook is an example for the last option.\n", "The results of the following code cells are not stored within the notebook, therefore it is executed during the Sphinx build process.\n", - "Since the above-mentioned `allow_errors` flag is set in this notebook, all cells are executed although most of them cause an exception." + "Since the above-mentioned `allow_errors` flag is set in this notebook's metadata, all cells are executed although most of them cause an exception." ] }, { @@ -102,7 +110,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.4.4rc1" + "version": "3.5.1+" }, "nbsphinx": { "allow_errors": true diff --git a/doc/conf.py b/doc/conf.py index 30741411..3b268d6b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -13,6 +13,9 @@ # Exclude build directory and Jupyter backup files: exclude_patterns = ['_build', '**.ipynb_checkpoints'] +# If True, the build process is continued even if an exception occurs: +#nbsphinx_allow_errors = True + # Default language for syntax highlighting (e.g. in Markdown cells) highlight_language = 'none' diff --git a/doc/pre-executed.ipynb b/doc/pre-executed.ipynb index 58a73f1c..e48058c8 100644 --- a/doc/pre-executed.ipynb +++ b/doc/pre-executed.ipynb @@ -125,7 +125,7 @@ "If an exception is raised during the Sphinx build process, it is stopped (the build process, not the exception!).\n", "If you want to show to your audience how an exception looks like, you have two choices:\n", "\n", - "1. Allow errors on a per-notebook basis, see [Ignoring Errors](allow-errors.ipynb).\n", + "1. Allow errors -- either generally or on a per-notebook basis -- see [Ignoring Errors](allow-errors.ipynb).\n", "\n", "1. Execute the notebook beforehand and save the results, like it's done in this example notebook:" ] @@ -170,7 +170,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.4.4rc1" + "version": "3.5.1+" } }, "nbformat": 4, diff --git a/nbsphinx.py b/nbsphinx.py index 42586c4b..73653a3b 100644 --- a/nbsphinx.py +++ b/nbsphinx.py @@ -332,8 +332,9 @@ class Exporter(nbconvert.RSTExporter): """ - def __init__(self): + def __init__(self, allow_errors=False): """Initialize the Exporter.""" + self._allow_errors = allow_errors loader = jinja2.DictLoader({'nbsphinx-rst.tpl': RST_TEMPLATE}) super(Exporter, self).__init__( template_file='nbsphinx-rst', extra_loaders=[loader], @@ -352,7 +353,8 @@ def from_notebook_node(self, nb, resources=None, **kw): # Execute notebook only if there are no outputs: if not any(c.outputs for c in nb.cells if 'outputs' in c): - allow_errors = nbsphinx_metadata.get('allow_errors', False) + allow_errors = (self._allow_errors or + nbsphinx_metadata.get('allow_errors', False)) pp = nbconvert.preprocessors.ExecutePreprocessor( allow_errors=allow_errors) nb, resources = pp.preprocess(nb, resources) @@ -399,8 +401,9 @@ def parse(self, inputstring, document): resources['output_files_dir'] = os.path.relpath(auxdir, srcdir) resources['unique_key'] = env.docname.replace('/', '_') + exporter = Exporter(allow_errors=env.config.nbsphinx_allow_errors) try: - rststring, resources = Exporter().from_notebook_node(nb, resources) + rststring, resources = exporter.from_notebook_node(nb, resources) except NotebookError as e: env.warn(env.docname, str(e)) return # document is unchanged (i.e. empty) @@ -832,6 +835,8 @@ def setup(app): """Initialize Sphinx extension.""" _add_notebook_parser(app) + app.add_config_value('nbsphinx_allow_errors', False, rebuild='') + app.add_directive('nbinput', NbInput) app.add_directive('nboutput', NbOutput) app.add_node(CodeNode,