Merge pull request #39 from jbweston/docs

add documentation page

Author: jbweston

README.md

@@ -1,7 +1,8 @@
 # Jupyter Sphinx Extensions
 
-Jupyter-sphinx enables the rendering of Jupyter interactive widgets in sphinx
-documentation.
+``jupyter-sphinx`` enables running code embedded in Sphinx documentation and
+embedding output of that code into the resulting document. It has support
+for rich output such as images and even Jupyter interactive widgets.
 
 ## Installation
 
@@ -17,76 +18,11 @@ with conda:
 conda install jupyter_sphinx -c conda-forge
 ```
 
-## Render Jupyter Interactive Widgets `jupyter_sphinx.embed_widgets`
+## Usage
 
-This extension provides a means of rendering Jupyter interactive widgets within
-sphinx documentation.
+You can check out the documentation on https://jupyter-sphinx.readthedocs.io for up to date
+usage information and examples.
 
-It is derived from the [`altair`](https://github.com/altair-viz/altair) sphinx
-extension, which is distributed under the terms of the BSD 3-Clause license.
-
-### Enabling the extension
-
-To enable this extension, add `jupyter_sphinx.embed_widgets` to your enabled
-extensions in `conf.py`.
-
-### Directives
-
-Two directives are provided: `ipywidgets-setup` and `ipywidgets-display`.
-
-`ipywidgets-setup` code is used to set-up various options
-prior to running the display code. For example:
-
-```rst
-.. ipywidgets-setup::
-
-	from ipywidgets import VBox, jsdlink, IntSlider, Button
-
-.. ipywidgets-display::
-
-    s1, s2 = IntSlider(max=200, value=100), IntSlider(value=40)
-    b = Button(icon='legal')
-    jsdlink((s1, 'value'), (s2, 'max'))
-    VBox([s1, s2, b])
-```
-
-In the case of the `ipywidgets-display` code, if the *last statement* of the
-code-block returns a widget object, it will be rendered.
-
-### Options
-
-The directives have the following options:
-
-```rst
-.. ipywidgets-setup::
-    :show: # if set, then show the setup code as a code block
-
-    from ipywidgets import Button
-
-.. ipywidgets-display::
-    :hide-code:   # if set, then hide the code and only show the widget
-    :code-below:  # if set, then code is below rather than above the widget
-    :alt: text    # alternate text when widget cannot be rendered
-
-    Button()
-```
-
-### Configuration
-
-File `conf.py` has two extra (optional) configuration options:
-
- * `jupyter_sphinx_require_url`: url for `require.js` (if your theme already provides this, set it to False or '')
- * `jupyter_sphinx_embed_url`: url for the embedding, if set to None (default) a proper default will be taken from the `ipywidgets.embed` module.
-
-### Misc.
-
-- For the widgets to be succesfuly rendered, this extension requires an
-  internet connection, since it depends on a cdn-served JavaScript file to be
-  loaded.
-- Widgets rendered on the same page use the same widget manager. As a
-  consequence, they can be linked with each other via JavaScript link widgets.
-  However, no kernel is connected and therefore, interaction with the backend
-  will not happen.
 
 ## License
 

doc/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/source/conf.py

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('../..'))
+
+import jupyter_sphinx
+
+project = 'Jupyter Sphinx'
+copyright = '2019, Jupyter Development Team'
+author = 'Jupyter Development Team'
+
+# The full version, including alpha/beta/rc tags
+release = jupyter_sphinx.__version__
+# The short X.Y version
+version = release[:len(release) - len(release.lstrip('0123456789.'))].rstrip('.')
+
+extensions = [
+    'sphinx.ext.mathjax',
+    'jupyter_sphinx.execute',
+]
+
+html_theme = 'alabaster'

doc/source/index.rst

@@ -0,0 +1,232 @@
+Jupyter Sphinx Extension
+========================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+Jupyter Sphinx is a Sphinx extension that executes embedded code in a Jupyter
+kernel, and embeds outputs of that code in the output document. It has support
+for rich output such as images, Latex math and even javascript widgets.
+
+Enabling the extension
+----------------------
+To enable the extension, add ``jupyter_sphinx.execute`` to your enabled extensions in
+``conf.py``.
+
+Basic Usage
+-----------
+
+You can use the ``jupyter-execute`` directive to embed code into the document::
+
+  .. jupyter-execute::
+
+    name = 'world'
+    print('hello ' + name + '!')
+
+The above is rendered as follows:
+
+.. jupyter-execute::
+
+  name = 'world'
+  print('hello ' + name + '!')
+
+Note that the code produces *output* (printing the string 'hello world!'), and the output
+is rendered directly after the code snippet.
+
+Because all code cells in a document are run in the same kernel, cells later in the document
+can use variables and functions defined in cells earlier in the document:
+
+.. jupyter-execute::
+
+    a = 1
+    print('first cell: a = {}'.format(a))
+
+.. jupyter-execute::
+
+    a += 1
+    print('second cell: a = {}'.format(a))
+
+Because jupyter-sphinx uses the machinery of ``nbconvert``, it is capable of rendering
+much richer output than mere text; plots, for example:
+
+.. jupyter-execute::
+
+    import numpy as np
+    from matplotlib import pyplot
+    %matplotlib inline
+
+    x = np.linspace(0, 2 * np.pi)
+
+    pyplot.plot(x, np.sin(x) / x)
+    pyplot.plot(x, np.cos(x))
+    pyplot.grid()
+
+or even full-blown javascript widgets:
+
+.. jupyter-execute::
+
+    import ipywidgets as w
+    from IPython.display import display
+
+    a = w.IntSlider()
+    b = w.IntText()
+    display(a, b)
+    w.jslink((a, 'value'), (b, 'value'))
+
+
+Directive options
+-----------------
+You may choose to hide the code of a cell, but keep its output visible using ``:hide-code:``::
+
+  .. jupyter-execute::
+      :hide-code:
+
+      print('this code is invisible')
+
+produces:
+
+.. jupyter-execute::
+    :hide-code:
+
+    print('this code is invisible')
+
+or vice versa with ``:hide-output:``::
+
+    .. jupyter-execute::
+        :hide-output:
+
+        print('this output is invisible')
+
+produces:
+
+.. jupyter-execute::
+    :hide-output:
+
+    print('this output is invisible')
+
+You may also display the code *below* the output with ``:code-below:``::
+
+  .. jupyter-execute::
+      :code-below:
+
+      print('this output is above the code')
+
+produces:
+
+.. jupyter-execute::
+    :code-below:
+
+    print('this code is below the output')
+
+
+Controlling exceptions
+----------------------
+
+The default behaviour when jupyter-sphinx encounters an error in the embedded code is just to
+stop execution of the document and display a stack trace. However, there are many cases where it may be
+illustrative for execution to continue and for a stack trace to be shown as *output of the cell*. This
+behaviour can be enabled by using the ``raises`` option::
+
+  .. jupyter-execute::
+      :raises:
+
+      1 / 0
+
+produces:
+
+.. jupyter-execute::
+    :raises:
+
+    1 / 0
+
+Note that when given no arguments, ``raises`` will catch all errors. It is also possible to give ``raises``
+a list of error types; if an error is raised that is not in the list then execution stops as usual::
+
+  .. jupyter-execute::
+      :raises: KeyError, ValueError
+
+      a = {'hello': 'world!'}
+      a['jello']
+
+produces:
+
+.. jupyter-execute::
+  :raises: KeyError, ValueError
+
+  a = {'hello': 'world!'}
+  a['jello']
+
+
+Controlling the execution environment
+-------------------------------------
+The execution environment can be controlled by using the ``jupyter-kernel`` directive. This directive takes
+the name of the Jupyter kernel in which all future cells (until the next ``jupyter-kernel`` directive) should
+be run::
+
+  .. jupyter-kernel:: python3
+      :id: a_unique_name
+
+``jupyter-kernel`` can also take a directive option ``:id:`` that names the Jupyter session;
+it is used in conjunction with the ``jupyter-download`` roles described in the next section.
+
+Note that putting a ``jupyter-kernel`` directive starts a *new* kernel, so any variables and functions declared
+in cells *before* a ``jupyter-kernel`` directive will not be available in future cells.
+
+Note that we are also not limited to working with Python: Jupyter Sphinx supports kernels for
+any programming language, and we even get proper syntax highlighting thanks to the power of
+Pygments.
+
+Downloading the code as a script
+--------------------------------
+Jupyter Sphinx includes 2 roles that can be used to download the code embedded in a document:
+``:jupyter-download:script:`` (for a raw script file) and ``:jupyter-download:notebook:`` (for
+a Jupyter notebook). For example, to download all the code from this document as a script we
+would use::
+
+    :jupyter-download:script:`index`
+
+Which produces a link like this: :jupyter-download:script:`index`. The name that the role is
+applied to (``index`` in this case) is the name of the document for which you wish to download
+the code. If a document contains ``jupyter-kernel`` directives with ``:id:`` specified, then
+the name provided to ``:id:`` can be used to get the code for the cells belonging to the
+that Jupyter session.
+
+
+Configuration options
+---------------------
+
+Typically you will be using Sphinx to build documentation for a software package.
+
+If you are building documentation for a Python package you should add the following
+lines to your sphinx ``conf.py``::
+
+    import os
+
+    package_path = os.path.abspath('../..')
+    os.environ['PYTHONPATH'] = ':'.join((package_path, os.environ.get('PYTHONPATH', '')))
+
+This will ensure that your package is importable by any IPython kernels, as they will
+inherit the environment variables from the main Sphinx process.
+
+Here is a list of all the configuration options available to the Jupyter Sphinx extension:
+
+jupyter_execute_default_kernel
+
+    The default kernel to launch when executing code in ``jupyter-execute`` directives.
+    The default is ``python3``.
+
+
+jupyter_execute_data_priority
+
+    The display priority of different output mimetypes. Mimetypes earlier in the data priority
+    list are preferred over later ones. This is relevant if a code cell produces an output
+    that has several possible representations (e.g. description text or an image).
+    The default is
+    ``['application/vnd.jupyter.widget-view+json', 'text/html', 'image/svg+xml', 'image/png', 'image/jpeg', 'text/latex', 'text/plain']``.
+
+
+jupyter_execute_kwargs
+
+    Keyword arguments to pass to ``nbconvert.preprocessors.execute.executenb``, which controls how
+    code cells are executed. The default is ``dict(timeout=-1, allow_errors=True)``.

environment.yml

@@ -0,0 +1,15 @@
+name: jupyter-sphinx
+
+channels:
+  - conda-forge
+
+dependencies:
+  - python=3.6
+  - sphinx>=0.6
+  - ipywidgets>=7.0.0
+  - IPython
+  - nbconvert>=5.4
+  - nbformat
+  # For documentation building and testing
+  - matplotlib
+  - pytest

readthedocs.yml

@@ -0,0 +1,2 @@
+conda:
+    environment: environment.yml