Merge pull request #8 from phobson/fancy-docs

notebook-based infrastructure

.gitignore

@@ -53,6 +53,9 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+.ipynb_checkpoints
+docs/tutorial/*.rst
+docs/tutorial/*_files/
 
 # PyBuilder
 target/

README.md

@@ -9,14 +9,17 @@ Simply importing `probscale` lets you use probability scales in your matplotlib
 ```python
 import matplotlib.pyplot as plt
 import probscale
+import seaborn
+clear_bkgd = {'axes.facecolor':'none', 'figure.facecolor':'none'}
+seaborn.set(style='ticks', context='notebook', rc=clear_bkgd)
 
-plt.style.use('ggplot')
 fig, ax = plt.subplots(figsize=(8, 4))
 ax.set_ylim(1e-2, 1e2)
 ax.set_yscale('log')
 
 ax.set_xlim(0.5, 99.5)
 ax.set_xscale('prob')
+seaborn.despine(fig=fig)
 ```
 
 ![Alt text](docs/img/example.png "Example axes")

docs/conf.py

@@ -28,13 +28,7 @@
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
-from recommonmark.parser import CommonMarkParser
-
-source_parsers = {
-    '.md': CommonMarkParser,
-}
-
-source_suffix = ['.rst', '.md']
+source_suffix = ['.rst']
 
 numpydoc_show_class_members = False
 autodoc_member_order = 'bysource'
@@ -43,14 +37,19 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
+sys.path.insert(0, os.path.abspath('sphinxext'))
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
+    'plot_generator',
+    'plot_directive',
     'numpydoc',
+    'ipython_directive',
+    'ipython_console_highlighting',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/examples/index.rst

@@ -0,0 +1,85 @@
+
+
+.. raw:: html
+
+    <style type="text/css">
+    .figure {
+        position: relative;
+        float: left;
+        margin: 10px;
+        width: 180px;
+        height: 200px;
+    }
+
+    .figure img {
+        position: absolute;
+        display: inline;
+        left: 0;
+        width: 170px;
+        height: 170px;
+        opacity:1.0;
+        filter:alpha(opacity=100); /* For IE8 and earlier */
+    }
+
+    .figure:hover img {
+        -webkit-filter: blur(3px);
+        -moz-filter: blur(3px);
+        -o-filter: blur(3px);
+        -ms-filter: blur(3px);
+        filter: blur(3px);
+        opacity:1.0;
+        filter:alpha(opacity=100); /* For IE8 and earlier */
+    }
+
+    .figure span {
+        position: absolute;
+        display: inline;
+        left: 0;
+        width: 170px;
+        height: 170px;
+        background: #000;
+        color: #fff;
+        visibility: hidden;
+        opacity: 0;
+        z-index: 100;
+    }
+
+    .figure p {
+        position: absolute;
+        top: 45%;
+        width: 170px;
+        font-size: 110%;
+    }
+
+    .figure:hover span {
+        visibility: visible;
+        opacity: .4;
+    }
+
+    .caption {
+        position: absolue;
+        width: 180px;
+        top: 170px;
+        text-align: center !important;
+    }
+    </style>
+
+.. _example_gallery:
+
+Example gallery
+===============
+
+
+
+.. toctree::
+   :hidden:
+
+
+
+
+
+
+
+.. raw:: html
+
+    <div style="clear: both"></div>

docs/index.rst

@@ -21,28 +21,40 @@ Simply importing ``probscale`` lets you use probability scales in your matplotli
 
     import matplotlib.pyplot as plt
     import probscale
+    import seaborn
+    clear_bkgd = {'axes.facecolor':'none', 'figure.facecolor':'none'}
+    seaborn.set(style='ticks', context='notebook', rc=clear_bkgd)
 
-    plt.style.use('ggplot')
     fig, ax = plt.subplots(figsize=(8, 4))
     ax.set_ylim(1e-2, 1e2)
     ax.set_yscale('log')
 
     ax.set_xlim(0.5, 99.5)
     ax.set_xscale('prob')
+    seaborn.despine(fig=fig)
 
 
 .. image:: /img/example.png
 
 
+Tutorial
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorial/getting_started.rst
+
 API References
-==============
+--------------
 
 .. toctree::
    :maxdepth: 2
 
+   probscale.rst
    viz.rst
 
-   probscale.rst
+
 
 
 Indices and tables

docs/sphinxext/ipython_console_highlighting.py

@@ -0,0 +1,116 @@
+"""reST directive for syntax-highlighting ipython interactive sessions.
+
+XXX - See what improvements can be made based on the new (as of Sept 2009)
+'pycon' lexer for the python console.  At the very least it will give better
+highlighted tracebacks.
+"""
+
+#-----------------------------------------------------------------------------
+# Needed modules
+
+# Standard library
+import re
+
+# Third party
+from pygments.lexer import Lexer, do_insertions
+from pygments.lexers.agile import (PythonConsoleLexer, PythonLexer,
+                                   PythonTracebackLexer)
+from pygments.token import Comment, Generic
+
+from sphinx import highlighting
+
+#-----------------------------------------------------------------------------
+# Global constants
+line_re = re.compile('.*?\n')
+
+#-----------------------------------------------------------------------------
+# Code begins - classes and functions
+
+
+class IPythonConsoleLexer(Lexer):
+
+    """
+    For IPython console output or doctests, such as:
+
+    .. sourcecode:: ipython
+
+      In [1]: a = 'foo'
+
+      In [2]: a
+      Out[2]: 'foo'
+
+      In [3]: print(a)
+      foo
+
+      In [4]: 1 / 0
+
+    Notes:
+
+      - Tracebacks are not currently supported.
+
+      - It assumes the default IPython prompts, not customized ones.
+    """
+
+    name = 'IPython console session'
+    aliases = ['ipython']
+    mimetypes = ['text/x-ipython-console']
+    input_prompt = re.compile("(In \[[0-9]+\]: )|(   \.\.\.+:)")
+    output_prompt = re.compile("(Out\[[0-9]+\]: )|(   \.\.\.+:)")
+    continue_prompt = re.compile("   \.\.\.+:")
+    tb_start = re.compile("\-+")
+
+    def get_tokens_unprocessed(self, text):
+        pylexer = PythonLexer(**self.options)
+        tblexer = PythonTracebackLexer(**self.options)
+
+        curcode = ''
+        insertions = []
+        for match in line_re.finditer(text):
+            line = match.group()
+            input_prompt = self.input_prompt.match(line)
+            continue_prompt = self.continue_prompt.match(line.rstrip())
+            output_prompt = self.output_prompt.match(line)
+            if line.startswith("#"):
+                insertions.append((len(curcode),
+                                   [(0, Comment, line)]))
+            elif input_prompt is not None:
+                insertions.append((len(curcode),
+                                   [(0, Generic.Prompt, input_prompt.group())]))
+                curcode += line[input_prompt.end():]
+            elif continue_prompt is not None:
+                insertions.append((len(curcode),
+                                   [(0, Generic.Prompt, continue_prompt.group())]))
+                curcode += line[continue_prompt.end():]
+            elif output_prompt is not None:
+                # Use the 'error' token for output.  We should probably make
+                # our own token, but error is typicaly in a bright color like
+                # red, so it works fine for our output prompts.
+                insertions.append((len(curcode),
+                                   [(0, Generic.Error, output_prompt.group())]))
+                curcode += line[output_prompt.end():]
+            else:
+                if curcode:
+                    for item in do_insertions(insertions,
+                                              pylexer.get_tokens_unprocessed(curcode)):
+                        yield item
+                        curcode = ''
+                        insertions = []
+                yield match.start(), Generic.Output, line
+        if curcode:
+            for item in do_insertions(insertions,
+                                      pylexer.get_tokens_unprocessed(curcode)):
+                yield item
+
+
+def setup(app):
+    """Setup as a sphinx extension."""
+
+    # This is only a lexer, so adding it below to pygments appears sufficient.
+    # But if somebody knows that the right API usage should be to do that via
+    # sphinx, by all means fix it here.  At least having this setup.py
+    # suppresses the sphinx warning we'd get without it.
+    pass
+
+#-----------------------------------------------------------------------------
+# Register the extension as a valid pygments lexer
+highlighting.lexers['ipython'] = IPythonConsoleLexer()