Clarify ipython_kernel_config.py usage, require traitlets>=5

Author: mgeier

doc/code-cells.ipynb

@@ -310,8 +310,22 @@
    "source": [
     "### Plots\n",
     "\n",
-    "The output formats for Matplotlib plots can be customized.\n",
-    "You'll need separate settings for the Jupyter Notebook application and for `nbsphinx`.\n",
+    "The output formats for Matplotlib plots can be customized\n",
+    "via the IPython configuration file `ipython_kernel_config.py`.\n",
+    "This file can be either\n",
+    "in the directory where your notebook is located\n",
+    "(see the [ipython_kernel_config.py](ipython_kernel_config.py) in this directory),\n",
+    "or in your profile directory\n",
+    "(typically `~/.ipython/profile_default/ipython_kernel_config.py`).\n",
+    "To find out your IPython profile directory, use this command:\n",
+    "\n",
+    "    python3 -m IPython profile locate\n",
+    "\n",
+    "A local `ipython_kernel_config.py` in the notebook directory\n",
+    "also works on https://mybinder.org/.\n",
+    "Alternatively, you can create a file with those settings in a file named\n",
+    "`.ipython/profile_default/ipython_kernel_config.py` in your repository.\n",
+    "\n",
     "\n",
     "If you want to use SVG images for Matplotlib plots,\n",
     "add this line to your IPython configuration file:\n",
@@ -342,22 +356,10 @@
     "For more details on these and other settings, have a look at\n",
     "[Default Values for Matplotlib's \"inline\" Backend](https://nbviewer.jupyter.org/github/mgeier/python-audio/blob/master/plotting/matplotlib-inline-defaults.ipynb).\n",
     "\n",
-    "The configuration file `ipython_kernel_config.py` can be either\n",
-    "in the directory where your notebook is located\n",
-    "(see the [ipython_kernel_config.py](ipython_kernel_config.py) in this directory),\n",
-    "or in your profile directory\n",
-    "(typically `~/.ipython/profile_default/ipython_kernel_config.py`).\n",
-    "To find out your IPython profile directory, use this command:\n",
-    "\n",
-    "    python3 -m IPython profile locate\n",
-    "\n",
-    "A local `ipython_kernel_config.py` in the notebook directory\n",
-    "also works on https://mybinder.org/.\n",
-    "Alternatively, you can create a file with those settings in a file named\n",
-    "`.ipython/profile_default/ipython_kernel_config.py` in your repository.\n",
-    "\n",
-    "To get SVG and PDF plots for `nbsphinx`,\n",
-    "use something like this in your `conf.py` file:\n",
+    "If you for some reason can't use a `ipython_kernel_config.py` file,\n",
+    "you can also change these settings with\n",
+    "[nbsphinx_execute_arguments](usage.ipynb#nbsphinx_execute_arguments)\n",
+    "in your `conf.py` file:\n",
     "\n",
     "```python\n",
     "nbsphinx_execute_arguments = [\n",
@@ -679,6 +681,8 @@
    ]
   },
   {
+   "cell_type": "markdown",
+   "metadata": {},
    "source": [
     "#### Troubleshooting\n",
     "\n",
@@ -708,9 +712,7 @@
     "\n",
     "- If the widgets are **not displayed**, see [#519](https://github.com/spatialaudio/nbsphinx/issues/519).\n",
     "- If the widgets are **displayed multiple times**, see [#378](https://github.com/spatialaudio/nbsphinx/issues/378)."
-   ],
-   "cell_type": "markdown",
-   "metadata": {}
+   ]
   },
   {
    "cell_type": "markdown",
@@ -868,7 +870,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.5"
+   "version": "3.9.9"
   }
  },
  "nbformat": 4,

doc/conf.py

@@ -1,6 +1,6 @@
 import os
 
-# Use sphinx-quickstart to create your own conf.py file!
+# You can use sphinx-quickstart to create your own conf.py file!
 # After that, you have to edit a few things.  See below.
 
 # Select nbsphinx and, if needed, other Sphinx extensions:
@@ -26,12 +26,6 @@
 # Don't add .txt suffix to source files:
 html_sourcelink_suffix = ''
 
-# List of arguments to be passed to the kernel that executes the notebooks:
-nbsphinx_execute_arguments = [
-    "--InlineBackend.figure_formats={'svg', 'pdf'}",
-    "--InlineBackend.rc=figure.dpi=96",
-]
-
 # Environment variables to be passed to the kernel:
 os.environ['MY_DUMMY_VARIABLE'] = 'Hello from conf.py!'
 

doc/ipython_kernel_config.py

@@ -1,2 +1,2 @@
-c.InlineBackend.figure_formats = {'svg'}
+c.InlineBackend.figure_formats = {'svg', 'pdf'}
 c.InlineBackend.rc = {'figure.dpi': 96}

doc/usage.ipynb

@@ -297,19 +297,6 @@
     "\n",
     "Kernel arguments used when executing notebooks.\n",
     "\n",
-    "If you [use Matplotlib for plots](code-cells.ipynb#Plots),\n",
-    "this setting is recommended:\n",
-    "\n",
-    "```python\n",
-    "nbsphinx_execute_arguments = [\n",
-    "    \"--InlineBackend.figure_formats={'svg', 'pdf'}\",\n",
-    "    \"--InlineBackend.rc=figure.dpi=96\",\n",
-    "]\n",
-    "```\n",
-    "\n",
-    "If you don't use LaTeX/PDF output,\n",
-    "you can drop the `'pdf'` figure format.\n",
-    "\n",
     "See [Configuring the Kernels](configuring-kernels.ipynb#Kernel-Arguments)."
    ]
   },
@@ -935,7 +922,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.2"
+   "version": "3.9.9"
   }
  },
  "nbformat": 4,

setup.py

@@ -17,7 +17,7 @@
         'docutils',
         'jinja2',
         'nbconvert!=5.4',
-        'traitlets',
+        'traitlets>=5',
         'nbformat',
         'sphinx>=1.8',
     ],