mirror of
https://github.com/wassname/jupyter_contrib_nbextensions.git
synced 2026-07-19 11:24:34 +08:00
96 lines
3.9 KiB
ReStructuredText
96 lines
3.9 KiB
ReStructuredText
Jupyter configuration files
|
|
===========================
|
|
|
|
Jupyter configuration is based on the :mod:`traitlets.config` module.
|
|
Essentially, each Jupyter application (e.g. :mod:`notebook`, or
|
|
:mod:`nbconvert`) has a number of configurable values which:
|
|
|
|
1. have default values
|
|
2. can be altered form their default by values read from configuration files,
|
|
which can be
|
|
a) ``.json`` static files
|
|
b) ``.py`` config python scripts
|
|
3. can be overridden by command-line arguments
|
|
|
|
|
|
.. _jupyter-config-path:
|
|
|
|
Jupyter config path
|
|
-------------------
|
|
|
|
Jupyter applications search for configuration files in each directory in the
|
|
*jupyter config path*. This path includes different locations in different
|
|
operating systems, but you can use the root jupyter command to find a list of
|
|
all jupyter paths, and look for the config section::
|
|
|
|
jupyter --paths
|
|
|
|
There are at least three configuration directories
|
|
|
|
1. a per-user directory
|
|
2. a directory in the ``sys.prefix`` directory for the python installation in
|
|
use
|
|
3. a system-wide directory
|
|
|
|
Note that it is likely that to write to the system-wide config directory will
|
|
require elevated (admin) privileges. This may also be true for the sys-prefix
|
|
directory, depending on the python installation in use.
|
|
|
|
Finally, you can also specify a configuration file as a command line argument,
|
|
for example::
|
|
|
|
jupyter notebook --config=/home/john/mystuff/jupyter_notebook_config.json
|
|
|
|
Note that this can change which filenames are searched for, as noted below.
|
|
|
|
|
|
.. _jupyter-config-filenames:
|
|
|
|
Jupyter configuration filenames
|
|
-------------------------------
|
|
|
|
Jupyter applications search the :ref:`jupyter-config-path` for config files
|
|
with names derived from the application name, with file extension of either
|
|
``.json`` (loaded as json) or ``.py`` (run as a python script).
|
|
For example, the ``jupyter notebook`` application searches for config files
|
|
called ``jupyter_notebook_config``, while the ``jupyter nbconvert`` application
|
|
searches for config files named ``jupyter_nbconvert_config``, with the file
|
|
extensions mentioned above.
|
|
In addition, all jupyter applications will load config files named
|
|
``jupyter_config.json`` or ``jupyter_config.py``.
|
|
|
|
Specifying a config file on the command line has the additional slightly subtle
|
|
effect that it will also change the filename that the application searches for.
|
|
For example, if I call the notebook using ::
|
|
|
|
jupyter notebook --config=/home/john/mystuff/special_config_ftw.json
|
|
|
|
then instead of searching the :ref:`jupyter-config-path` for files named
|
|
``jupyter_notebook_config``, the notebook application will search the config
|
|
path for other files also named ``special_config_ftw``, which can mean that the
|
|
normal config files get missed. As a result, it may be preferable to name any
|
|
custom config files with the standard filename for the jupyter application they
|
|
pertain to.
|
|
|
|
|
|
.. _jupyter-contrib-nbextensions-config-edits:
|
|
|
|
Config files edited by jupyter_contrib_nbextensions
|
|
---------------------------------------------------
|
|
|
|
The ``jupyter contrib nbextensions install`` command edits some config files as
|
|
part of the install:
|
|
|
|
* ``jupyter_notebook_config.json`` is edited in order to:
|
|
- enable the
|
|
`jupyter_nbextensions_configurator <https://github.com/Jupyter-contrib/jupyter_nbextensions_configurator>`__.
|
|
serverextension
|
|
- enable the ``contrib_nbextensions_help_item`` nbextension, which adds
|
|
a link to readthedocs to the help menu
|
|
* ``jupyter_nbconvert_config.json`` is edited in order to:
|
|
- edit the nbconvert template path, adding the
|
|
``jupyter_contrib_nbextensions.nbconvert_support`` templates directory
|
|
- add preprocessors ``CodeFoldingPreprocessor`` and
|
|
``PyMarkdownPreprocessor`` from the
|
|
``jupyter_contrib_nbextensions.nbconvert_support`` module
|