From 61a538208323dbe5addd9ac02ad06b7d1d605a19 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 22 Sep 2015 08:34:17 -0700 Subject: [PATCH 1/4] Add frontend configuration doc --- docs/source/frontend_config.rst | 67 +++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + 2 files changed, 68 insertions(+) create mode 100644 docs/source/frontend_config.rst diff --git a/docs/source/frontend_config.rst b/docs/source/frontend_config.rst new file mode 100644 index 000000000..a02dbd922 --- /dev/null +++ b/docs/source/frontend_config.rst @@ -0,0 +1,67 @@ +.. _frontend_config: + +Configuring the notebook frontend +================================= + +The ability to configure the UI and the preferences on the notebook frontend is +still work in progress. This document is a rough explanation on how you can +persist some configuration options for the notebook JavaScript. + +There is no exhaustive list on all the configuration option are most options +are just passed down to other libraries, which mean that non valid +configuration can be ignored without any error messages. + + +The frontend configuration system works as follow : + + - get a handle of a configurable JavaScript object. + - access it's configuration attribute. + - update it's configuration attribute with a JSON patch. + +Here is a example on how it's look like for changing the default ``indentUnit`` +for CodeMirror Code Cells: + +.. sourcecode:: + + var cell = Jupyter.notebook.get_selected_cell(); + var config = cell.config; + var patch = { + CodeCell:{ + cm_config:{indentUnit:2} + } + } + config.update(patch) + + + +You can enter the previous snippet in your browser console once, reload the +notebook page. Now the default indent unit of all code cell should be equal to +2 space. You do not need to reissue the command on new notebooks. + + + +``indentUnit`` is here a `Codemirror option +`_ taken as an +example, but many other configuration options are available. + +If you need to restore the default value just provide a JSON patch with +``null`` value. For example to restore the indent value to it's default (of 4) +write the following on your JavaScript console: + +.. sourcecode:: + + var cell = Jupyter.notebook.get_selected_cell(); + var config = cell.config; + var patch = { + CodeCell:{ + cm_config:{indentUnit: null} # only change here. + } + } + config.update(patch) + + +Under the hood, it will persist the configuration file in +``~/.jupyter/nbconfig/
.json``, with section taking various value +depending on the page where the configuration is issued. ``section`` can take +various value like ``notebook``, ``tree``, ``editor``. A ``common`` section is +shared by all pages. diff --git a/docs/source/index.rst b/docs/source/index.rst index b4a38f71f..b2134aca6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,6 +13,7 @@ The Jupyter notebook :caption: Configuration config + frontend_config public_server security extending/index From 126c77c8337b70b1aff418cc4ece47c64c844b7a Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 22 Sep 2015 09:32:11 -0700 Subject: [PATCH 2/4] Update config docs --- docs/autogen_config.py | 5 ++- docs/source/frontend_config.rst | 70 +++++++++++++++++++-------------- docs/source/index.rst | 2 +- 3 files changed, 45 insertions(+), 32 deletions(-) diff --git a/docs/autogen_config.py b/docs/autogen_config.py index 0ee26a1db..f06efe917 100644 --- a/docs/autogen_config.py +++ b/docs/autogen_config.py @@ -6,8 +6,9 @@ from notebook.notebookapp import NotebookApp header = """\ .. _config: -Config -====== + +Config file and command line options +==================================== The notebook server can be run with a variety of command line arguments. A list of available options can be found below in the :ref:`options section diff --git a/docs/source/frontend_config.rst b/docs/source/frontend_config.rst index a02dbd922..1e7bfca02 100644 --- a/docs/source/frontend_config.rst +++ b/docs/source/frontend_config.rst @@ -3,25 +3,32 @@ Configuring the notebook frontend ================================= -The ability to configure the UI and the preferences on the notebook frontend is -still work in progress. This document is a rough explanation on how you can -persist some configuration options for the notebook JavaScript. +.. note:: + + The ability to configure the notebook frontend UI and preferences is + still a work in progress. + +This document is a rough explanation on how you can persist some configuration +options for the notebook JavaScript. There is no exhaustive list on all the configuration option are most options are just passed down to other libraries, which mean that non valid configuration can be ignored without any error messages. -The frontend configuration system works as follow : +How front end configuration works +--------------------------------- +The frontend configuration system works as follows:: - get a handle of a configurable JavaScript object. - - access it's configuration attribute. - - update it's configuration attribute with a JSON patch. + - access its configuration attribute. + - update its configuration attribute with a JSON patch. -Here is a example on how it's look like for changing the default ``indentUnit`` -for CodeMirror Code Cells: -.. sourcecode:: +Example - Changing the notebook's default indentation +----------------------------------------------------- +This example explains how to change the default setting ``indentUnit`` +for CodeMirror Code Cells:: var cell = Jupyter.notebook.get_selected_cell(); var config = cell.config; @@ -29,26 +36,26 @@ for CodeMirror Code Cells: CodeCell:{ cm_config:{indentUnit:2} } - } + } config.update(patch) +You can enter the previous snippet in your browser's JavaScript console once. +Then reload the notebook page in your browser. Now, the preferred indent unit +should be equal to two spaces. The custom setting persists and you do not need +to reissue the patch on new notebooks. - -You can enter the previous snippet in your browser console once, reload the -notebook page. Now the default indent unit of all code cell should be equal to -2 space. You do not need to reissue the command on new notebooks. +``indentUnit``, used in this example, is one of the many `Codemirror option +`_ which are available +for configuration. +Example - Restoring the notebook's default indentation +------------------------------------------------------ +If you want to restore a notebook frontend preference to its default value, +you will enter a JSON patch with a ``null`` value for the preference setting. -``indentUnit`` is here a `Codemirror option -`_ taken as an -example, but many other configuration options are available. - -If you need to restore the default value just provide a JSON patch with -``null`` value. For example to restore the indent value to it's default (of 4) -write the following on your JavaScript console: - -.. sourcecode:: +For example, let's restore the indent setting ``indentUnit`` to its default of +four spaces. Enter the following code snippet in your JavaScript console:: var cell = Jupyter.notebook.get_selected_cell(); var config = cell.config; @@ -59,9 +66,14 @@ write the following on your JavaScript console: } config.update(patch) - -Under the hood, it will persist the configuration file in -``~/.jupyter/nbconfig/
.json``, with section taking various value -depending on the page where the configuration is issued. ``section`` can take -various value like ``notebook``, ``tree``, ``editor``. A ``common`` section is -shared by all pages. +Reload the notebook in your browser and the default indent should again be two +spaces. + +Persisting conguration settings +------------------------------- +Under the hood, Jupyter will persist preferred configuration settings in the +configuration file in ``~/.jupyter/nbconfig/
.json``, with ``
`` +taking various value depending on the page where the configuration is issued. +``
`` can take various values like ``notebook``, ``tree``, and +``editor``. A ``common`` section contains configuration settings shared by all +pages. diff --git a/docs/source/index.rst b/docs/source/index.rst index b2134aca6..d02bfc07f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,9 +13,9 @@ The Jupyter notebook :caption: Configuration config - frontend_config public_server security + frontend_config extending/index .. toctree:: From 364e8fe2e0c61db564c6be3091cef4aed9fbc759 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 22 Sep 2015 10:18:13 -0700 Subject: [PATCH 3/4] Minor edits --- docs/source/frontend_config.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/frontend_config.rst b/docs/source/frontend_config.rst index 1e7bfca02..2eb91b8a0 100644 --- a/docs/source/frontend_config.rst +++ b/docs/source/frontend_config.rst @@ -18,7 +18,7 @@ configuration can be ignored without any error messages. How front end configuration works --------------------------------- -The frontend configuration system works as follows:: +The frontend configuration system works as follows: - get a handle of a configurable JavaScript object. - access its configuration attribute. @@ -44,7 +44,7 @@ Then reload the notebook page in your browser. Now, the preferred indent unit should be equal to two spaces. The custom setting persists and you do not need to reissue the patch on new notebooks. -``indentUnit``, used in this example, is one of the many `Codemirror option +``indentUnit``, used in this example, is one of the many `CodeMirror options `_ which are available for configuration. @@ -71,8 +71,8 @@ spaces. Persisting conguration settings ------------------------------- -Under the hood, Jupyter will persist preferred configuration settings in the -configuration file in ``~/.jupyter/nbconfig/
.json``, with ``
`` +Under the hood, Jupyter will persist the preferred configuration settings in +``~/.jupyter/nbconfig/
.json``, with ``
`` taking various value depending on the page where the configuration is issued. ``
`` can take various values like ``notebook``, ``tree``, and ``editor``. A ``common`` section contains configuration settings shared by all From 786a35052715b6a19ed688f2214b885331a9ffe2 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Wed, 23 Sep 2015 22:43:26 -0700 Subject: [PATCH 4/4] Fix grammar from review comments --- docs/source/frontend_config.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/frontend_config.rst b/docs/source/frontend_config.rst index 2eb91b8a0..6c4280ad5 100644 --- a/docs/source/frontend_config.rst +++ b/docs/source/frontend_config.rst @@ -11,8 +11,8 @@ Configuring the notebook frontend This document is a rough explanation on how you can persist some configuration options for the notebook JavaScript. -There is no exhaustive list on all the configuration option are most options -are just passed down to other libraries, which mean that non valid +There is no exhaustive list of all the configuration options as most options +are passed down to other libraries, which means that non valid configuration can be ignored without any error messages. @@ -69,8 +69,8 @@ four spaces. Enter the following code snippet in your JavaScript console:: Reload the notebook in your browser and the default indent should again be two spaces. -Persisting conguration settings -------------------------------- +Persisting configuration settings +--------------------------------- Under the hood, Jupyter will persist the preferred configuration settings in ``~/.jupyter/nbconfig/
.json``, with ``
`` taking various value depending on the page where the configuration is issued.