New Demo Mode

.travis.yml

@@ -7,7 +7,7 @@ python:
     - 2.7
 sudo: false
 install:
-    - travis_retry pip install ipython nose requests
+    - travis_retry pip install ipython nose requests mock
     - python setup.py develop
 script:
     - python test.py

docs/Makefile

@@ -59,10 +59,7 @@ dist: html
 	cp -al build/html .
 	@echo "Build finished.  Final docs are in html/"
 
-html: api autoconfig automagic
-html_noapi: clean_api autoconfig automagic
-
-html html_noapi:
+html html_noapi: automagic
 	mkdir -p build/html build/doctrees
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
 	@echo
@@ -74,18 +71,6 @@ source/interactive/magics-generated.txt: autogen_magics.py
 	python autogen_magics.py
 	@echo "Created docs for line & cell magics"
 
-autoconfig: source/config/options/generated
-
-source/config/options/generated:
-	python autogen_config.py
-	@echo "Created docs for config options"
-
-api: source/api/generated/gen.txt
-
-source/api/generated/gen.txt:
-	python autogen_api.py
-	@echo "Build API docs finished."
-
 pickle:
 	mkdir -p build/pickle build/doctrees
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle

docs/autogen_magics.py

@@ -1,4 +1,5 @@
 import os
+import sys
 
 from IPython.core.alias import Alias
 from IPython.core.interactiveshell import InteractiveShell
@@ -16,6 +17,9 @@
 for name, func in magics['cell'].items():
     ipy_magics.append(name)
 
+# put the package itself into the path so we can run the build without installing
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
 from ipyext import all_class_magics
 shell.register_magics(*all_class_magics)
 

docs/source/conf.py

@@ -39,6 +39,9 @@
 # absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../sphinxext'))
 
+# put the package itself into the path so we can run the build without installing
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")))
+
 # We load the ipython release info into a dict by explicit execution
 ipextrelease = {}
 exec(compile(open('../../ipyext/_version.py').read(), '../../ipyext/_version.py', 'exec'),ipextrelease)
@@ -70,6 +73,8 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+autosummary_generate = True
+
 # The suffix of source filenames.
 source_suffix = '.rst'
 

docs/source/demo_mode.rst

@@ -0,0 +1,87 @@
+.. currentmodule:: ipyext
+.. _demo_mode:
+
+*************
+Demo mode
+*************
+
+.. currentmodule:: ipyext.demo
+
+As a User
+---------
+
+There are currently two possible sources of demos:
+
+* plain (self contained) functions included in modules
+  of libraries you use.
+* the matplotlib examples in their github repository
+
+``demo(...)`` has two modes:
+
+* for a imported module or a directory on github, it will list the available demos.
+* for a function or a file on github, it will show the demo.
+
+Example:
+
+.. ipython:: python
+
+    from ipyext.demo import demo
+    import ipyext.demo
+    demo(ipyext.demo) # lists all demos
+    demo(ipyext.demo.demo_example) # runs the demo_example
+    demo("STOP") # stops an already running demo
+    demo("<gh_matplotlib>/statistics/") # lists demos from matplotlibs' examples
+
+
+Hiere is the API documentation of ``demo()``
+
+.. autosummary::
+   :toctree: generated/
+
+    demo
+
+As a developer
+--------------
+
+You can create demos by adding a new module which should contain two things:
+
+* One or more *self contained functions* which take *no arguments*. The
+  functions can have two types of *comments*: ``"# "`` (fence + space) are
+  interpreted as markdown (e.g. write ``"# # headline"``) and result in
+  markdown cells in the notebook and normal comments in the console.
+  Comments without a space are interpreted as code comments and added
+  directly to the following code input. You can add a *one line docstring*
+  which will be shown as description of the demo in the list of available
+  demos. Using *IPython magic methods* are also possible but must be
+  commented.
+* A ``__demos__`` field in the module which *lists all demo functions* (direct
+  reference, not strings like in ``__all__``!).
+
+Example:
+
+.. code-block:: python
+
+    def demo_example():
+        """An example how to write a demo."""
+        # ## Comments
+        # Comments are interpreted as markdown syntax, removing the
+        # initial `# `. If a comment starts only with `#`, it is interpreted
+        # as a code comment, which will end up together with the code.
+        #change your name:
+        name = "Jan"
+        print("Hello {0}!".format(name))
+        # ## Magics
+        # Using magics would result in not compiling code, so magics
+        # have to be commented out. The demo will remove the comment
+        # and insert it into the cell as code.
+        #%%time
+        _sum = 0
+        for x in range(10000):
+            _sum += x
+        # Print the sum:
+        print(_sum)
+
+    # This lets the `demo(ipyext.demo)` find only the `demo_example`.
+    # Only modues with that variable will display an overview of
+    # the available demos.
+    __demos__ = [demo_example]

docs/source/generated/ipyext.demo.demo.rst

@@ -0,0 +1,6 @@
+ipyext.demo.demo
+================
+
+.. currentmodule:: ipyext.demo
+
+.. autofunction:: demo

docs/source/index.rst

@@ -18,6 +18,7 @@ Contents
 
    install
    magics
+   demo_mode
    whatsnew
 
 .. seealso::