Merge pull request ipython-contrib#833 from jcb91/readme_and_docs

Readme and docs

docs/source/conf.py

@@ -26,7 +26,9 @@
     'ipython': ('http://ipython.org/ipython-doc/dev/', None),
     'nbconvert': ('http://nbconvert.readthedocs.io/en/latest/', None),
     'nbformat': ('http://nbformat.readthedocs.io/en/latest/', None),
+    'notebook': ('http://jupyter-notebook.readthedocs.io/en/latest/', None),
     'jupyter': ('http://jupyter.readthedocs.io/en/latest/', None),
+    'traitlets': ('http://traitlets.readthedocs.io/en/latest/', None),
 }
 
 # General information about the project.

docs/source/config.rst

@@ -0,0 +1,95 @@
+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

docs/source/exporting.rst

@@ -18,19 +18,21 @@ Preprocessors
 -------------
 
 Generic documentation for preprocessors can be found at
-http://nbconvert.readthedocs.io/en/latest/api/preprocessors.html.
+`nbconvert.readthedocs.io/en/latest/api/preprocessors.html <http://nbconvert.readthedocs.io/en/latest/api/preprocessors.html>`__.
+
 
 Retaining Codefolding
 ^^^^^^^^^^^^^^^^^^^^^
 
 .. autoclass:: CodeFoldingPreprocessor
 
 
-Coallapsible Headings
-^^^^^^^^^^^^^^^^^^^^^
+Collapsible Headings
+^^^^^^^^^^^^^^^^^^^^
 
 .. autoclass:: CollapsibleHeadingsPreprocessor
 
+
 Retaining Highlighting
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -42,6 +44,7 @@ Evaluating code in Markdown (PyMarkDown)
 
 .. autoclass:: PyMarkdownPreprocessor
 
+
 Converting linked SVG to PDF
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -52,8 +55,9 @@ Converting linked SVG to PDF
 Postprocessors
 --------------
 
-Generic documentation for postprocessors can be found here
-http://nbconvert.readthedocs.io/en/latest/api/postprocessors.html
+Generic documentation for postprocessors can be found at
+`nbconvert.readthedocs.io/en/latest/api/postprocessors.html <http://nbconvert.readthedocs.io/en/latest/api/postprocessors.html>`__
+
 
 Retaining Highlighting
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -65,7 +69,9 @@ Exporters
 ---------
 
 Generic documentation for exporters can be found at
-http://nbconvert.readthedocs.io/en/latest/api/exporters.html
+
+`nbconvert.readthedocs.io/en/latest/api/exporters.html <http://nbconvert.readthedocs.io/en/latest/api/exporters.html>`__
+
 
 Embed images in HTML
 ^^^^^^^^^^^^^^^^^^^^
@@ -77,6 +83,7 @@ Embed images in HTML
 
         jupyter nbconvert --to html_embed --NbConvertApp.codefolding=True mynotebook.ipynb
 
+
 Export Table of Contents
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -87,11 +94,19 @@ Templates
 ---------
 
 Generic documentation on templates can be found at
-http://nbconvert.readthedocs.io/en/latest/customizing.html
+`nbconvert.readthedocs.io/en/latest/customizing.html <http://nbconvert.readthedocs.io/en/latest/customizing.html>`__
+
+The main `jupyter contrib nbextension install` command will attempt to alter
+the nbconvert config to include the package's templates directory, as mentioned
+in :ref:`jupyter-contrib-nbextensions-config-edits`.
+This should allow you to use the templates `nbextensions.tpl` and
+`nbextensions.tplx` mentioned below just by specifying `--template=nbextensions`
+in your call to nbconvert.
 
 To find the location of the custom templates you can use this function:
 .. autofunction:: templates_directory
 
+
 Hiding cells
 ^^^^^^^^^^^^
 
@@ -105,4 +120,3 @@ The supported cell metadata tags are:
  * `cell.metadata.hidden` - hide complete cell
  * `cell.metadata.hide_input` - hide code cell input
  * `cell.metadata.hide_output` - hide code cell output
-

docs/source/index.rst

@@ -27,4 +27,5 @@ Contents:
    nbextensions
    troubleshooting
    exporting
+   config
    internals

docs/source/install.md

@@ -1,5 +1,5 @@
-Installing Jupyter Notebook Extensions
-======================================
+Installing jupyter_contrib_nbextensions
+=======================================
 
 To install the `jupyter_contrib_nbextensions` notebook extensions, three steps
 are required. First, the Python pip package needs to be installed. Then, the
@@ -26,7 +26,8 @@ To install the current version from PyPi, simply type
 
     pip install jupyter_contrib_nbextensions
 
-Alternatively, you can install directly from the current master branch of the repository
+Alternatively, you can install directly from the current master branch of the
+repository
 
     pip install https://github.com/ipython-contrib/jupyter_contrib_nbextensions/tarball/master
 
@@ -36,14 +37,16 @@ upgrade, or `-e` for an editable install.
 
 ### Conda
 
-There are conda packages for the notebook extensions and the notebook extensions configurator
-available from [conda-forge](https://conda-forge.github.io). You can install both using
+There are conda packages for the notebook extensions and the
+[jupyter_nbextensions_configurator](https://github.com/Jupyter-contrib/jupyter_nbextensions_configurator)
+available from [conda-forge](https://conda-forge.github.io).
+You can install both using
 
     conda install -c conda-forge jupyter_contrib_nbextensions
 
 This also automatically installs the Javascript and CSS files
-(using `jupyter contrib nbextension install --sys-prefix`), so the second installation step
-below can therefore be skipped.
+(using `jupyter contrib nbextension install --sys-prefix`), so the second
+installation step below can therefore be skipped.
 
 
 ### Installation from cloned Repo
@@ -85,7 +88,7 @@ including
  * `--debug`, for more-verbose output
 
 In addition, two further option flags are provided to perform either only the
-config-editing perations, or only the file-copy operations:
+config-editing operations, or only the file-copy operations:
 
  * `--only-files` to install nbextension files without editing any config files
  * `--only-config` to edit the config files without copying/symlinking any
@@ -116,11 +119,16 @@ To disable the extension again, use
 
     jupyter nbextension disable <nbextension require path>
 
-Alternatively, and more conveniently, you can use the
+**Alternatively**, and more conveniently, you can use the
 [jupyter_nbextensions_configurator](https://github.com/Jupyter-contrib/jupyter_nbextensions_configurator)
 server extension, which is installed as a dependency of this repo, and can be
 used to enable and disable the individual nbextensions, as well as configure
-their options.
+their options. You can then open the `nbextensions` tab on the tree
+(dashboard/file browser) notebook page to configure nbextensions.
+You will have access there to a dashboard where extensions can be
+enabled/disabled via checkboxes.
+Additionally a short documentation for each extension is displayed, and
+configuration options are presented.
 
 ![jupyter_nbextensions_configurator](https://raw.githubusercontent.com/Jupyter-contrib/jupyter_nbextensions_configurator/master/src/jupyter_nbextensions_configurator/static/nbextensions_configurator/icon.png)
 

docs/source/internals.rst

@@ -89,9 +89,9 @@ And for the `config.yaml` file:
       step: 1
       default: 100
 
-When supplying a `readme.md` file, please supply a main heading, as this will
-be linked in the generated documentation at
-[jupyter-contrib-nbextensions.readthedocs.io](http://jupyter-contrib-nbextensions.readthedocs.io/en/latest/).
+When supplying a `readme.md` file, please supply a main heading with the
+nbextension's title, as this will be linked in the generated documentation at
+`jupyter-contrib-nbextensions.readthedocs.io <http://jupyter-contrib-nbextensions.readthedocs.io/en/latest>`__.
 This is a simple example for `readme.md`:
 
 .. code-block:: markdown

src/jupyter_contrib_nbextensions/nbextensions/hide_input/readme.md

@@ -1,31 +1,70 @@
 Hide Input
 ==========
-This extension allows hiding of an individual codecell in a notebook. This can be achieved by clicking on the toolbar 
-button:
+
+This extension allows hiding of an individual codecell in a notebook. This can
+be achieved by clicking on the toolbar button:
+
 ![](icon.png)
 
+
 Internals
 ---------
 
 The codecell hiding state is stored in the metadata `cell.metadata.hide_input`.
 If it is set to `true`, the codecell will be hidden on reload.
 
-To export a notebook with hidden cells using nbconvert, you need to add a custom template and a custom filter:
-```
+
+Exporting with nbconvert
+------------------------
+
+See also the general docs for exporting using nbconvert at
+[jupyter-contrib-nbextensions.readthedocs.io](http://jupyter-contrib-nbextensions.readthedocs.io/en/latest).
+
+To export a notebook with hidden cell inputs using nbconvert, you need to use a
+custom template and a custom filter.
+The required filter and template are supplied as part of
+`jupyter_contrib_nbextensions.nbconvert_support`, or you can roll your own
+using the provided ones as examples. Again, see the docs linked above for more
+information.
+
+The `nbextensions.tpl` template is provided in the
+`jupyter_contrib_nbextensions.nbconvert_support` templates directory (see the
+docs mentioned above for how to find it), while the necessary
+`strip_output_prompt` filter, is provided by
+`jupyter_contrib_nbextension.nbconvert_support.strip_output_prompt`.
+
+An example of a python config file which will arrange to use the correct
+template and filter:
+
+```python
+import os
+import jupyter_contrib_nbextensions.nbconvert_support
+
 c = get_config()
-c.Exporter.template_file = 'nbextensions'
-c.Exporter.filters = {'strip_output_prompt': 'strip_output_prompt.strip_output_prompt'}
+c.Exporter.template_file = os.path.join(
+    jupyter_contrib_nbextensions.nbconvert_support.templates_directory(),
+    'nbextensions')
+c.Exporter.setdefault('filters', {})['strip_output_prompt'] = (
+    'jupyter_contrib_nbextensions.nbconvert_support.'
+    'strip_output_prompt.strip_output_prompt')
 ```
 
-The template will respect the `cell.metadata.hide_input` flag, and the filter will remove the cell output prompt 
-that looks like `Out[27]:`. The filter is not used for PDF or LaTeX output.
+To use, put this config into a file named `jupyter_nbconvert_config.py` in the
+same directory as the notebook you wish to convert, and call using
+
+    nbconvert --config=jupyter_nbconvert_config.py my_notebook.ipynb
+
+The nbextensions template will respect the `cell.metadata.hide_input` flag, and
+the filter will remove the cell's output prompt (the bit that looks like
+`Out[27]:`).
+The filter is only used for html output, not for PDF or LaTeX output.
+
+If you want to _keep_ the cell output prompt, you will have to change the line
+
+    {{ super() | strip_output_prompt }}
 
-If you want to keep the cell output prompt, you will have to change the line
-```
-   {{ super() | strip_output_prompt }}
-```
 to
-```
-   {{ super() }}
-```
-in the `nbextensions.tpl` file. 
+
+    {{ super() }}
+
+in the `nbextensions.tpl` file.