Merge pull request #1168 from fperez/nbscript

Add --script/--no-script flags as shorthands for the NotebookManager.save_script option.

IPython/frontend/html/notebook/notebookapp.py

@@ -52,7 +52,7 b' from .handlers import (LoginHandler, LogoutHandler,'
 )
 from .notebookmanager import NotebookManager
 
-from IPython.config.application import catch_config_error
+from IPython.config.application import catch_config_error, boolean_flag
 from IPython.core.application import BaseIPythonApplication
 from IPython.core.profiledir import ProfileDir
 from IPython.lib.kernel import swallow_argv
@@ -157,10 +157,15 b" flags['read-only'] = ("
     """
 )
 
+# Add notebook manager flags
+flags.update(boolean_flag('script', 'NotebookManager.save_script',
+               'Auto-save a .py script everytime the .ipynb notebook is saved',
+               'Do not auto-save .py scripts for every notebook'))
+
 # the flags that are specific to the frontend
 # these must be scrubbed before being passed to the kernel,
 # or it will raise an error on unrecognized flags
-notebook_flags = ['no-browser', 'no-mathjax', 'read-only']
+notebook_flags = ['no-browser', 'no-mathjax', 'read-only', 'script', 'no-script']
 
 aliases = dict(ipkernel_aliases)
 

IPython/frontend/html/notebook/notebookmanager.py

@@ -27,12 +27,10 b' from IPython.config.configurable import LoggingConfigurable'
 from IPython.nbformat import current
 from IPython.utils.traitlets import Unicode, List, Dict, Bool
 
-
 #-----------------------------------------------------------------------------
-# Code
+# Classes
 #-----------------------------------------------------------------------------
 
-
 class NotebookManager(LoggingConfigurable):
 
     notebook_dir = Unicode(os.getcwd(), config=True, help="""
@@ -40,10 +38,12 b' class NotebookManager(LoggingConfigurable):'
     """)
     
     save_script = Bool(False, config=True,
-        help="""Also save notebooks as a Python script.
+        help="""Automatically create a Python script when saving the notebook.
         
-        For easier use of import/%loadpy across notebooks, a <notebook-name>.py
-        script will be created next to any <notebook-name>.ipynb on each save.
+        For easier use of import, %run and %loadpy across notebooks, a
+        <notebook-name>.py script will be created next to any
+        <notebook-name>.ipynb on each save.  This can also be set with the
+        short `--script` flag.
         """
     )
     

docs/source/interactive/htmlnotebook.txt

@@ -187,15 +187,7 b' entire contents of the file will be loaded into a single code cell. But if'
 prior to import, you manually add the ``# <nbformat>2</nbformat>`` marker at
 the start and then add separators for text/code cells, you can get a cleaner
 import with the file broken into individual cells.
-
-If you want use notebooks as scripts a lot, then you can set::
-
-    c.NotebookManager.save_script=True
-
-which will instruct the notebook server to save the ``.py`` export of each
-notebook adjacent to the ``.ipynb`` at every save.  Then these can be ``%run``
-or imported from regular IPython sessions or other notebooks.
-
+    
 .. warning::
 
    While in simple cases you can roundtrip a notebook to Python, edit the
@@ -209,6 +201,48 b' or imported from regular IPython sessions or other notebooks.'
    notebook started.  But the Python version is *not* an alternate notebook
    format.
 
+   
+Importing or executing a notebook as a normal Python file
+---------------------------------------------------------
+
+The native format of the notebook, a file with a ``.ipynb`` extension, is a
+JSON container of all the input and output of the notebook, and therefore not
+valid Python by itself.  This means that by default, you can not import a
+notebook or execute it as a normal python script.  But if you want use
+notebooks as regular Python files, you can start the notebook server with::
+
+  ipython notebook --script
+
+or you can set this option permanently in your configuration file with::
+
+    c.NotebookManager.save_script=True
+
+This will instruct the notebook server to save the ``.py`` export of each
+notebook adjacent to the ``.ipynb`` at every save.  These files can be
+``%run``, imported from regular IPython sessions or other notebooks, or
+executed at the command-line as normal Python files.  Since we export the raw
+code you have typed, for these files to be importable from other code you will
+have to avoid using syntax such as ``%magics`` and other IPython-specific
+extensions to the language.
+
+In regular practice, the standard way to differentiate importable code from the
+'executable' part of a script is to put at the bottom::
+
+  if __name__ == '__main__':
+    # rest of the code...
+
+Since all cells in the notebook are run as top-level code, you'll need to
+similarly protect *all* cells that you do not want executed when other scripts
+try to import your notebook.  A convenient shortand for this is to define early
+on::
+
+  script = __name__ == '__main__':
+
+and then on any cell that you need to protect, use::
+
+  if script:
+    # rest of the cell...
+
     
 Keyboard use
 ------------