Merge pull request #171 from willingc/examples-doc

Document examples directory contents and docstrings to 'filebrowser' example

examples/console/main.py

@@ -1,6 +1,25 @@
 """
+An example demonstrating a stand-alone "console".
+
 Copyright (c) Jupyter Development Team.
 Distributed under the terms of the Modified BSD License.
+
+Example
+-------
+
+To run the example, make sure the Jupyter notebook server version 4.2+ is
+installed.
+
+- To build the JavaScript bundle: ``npm install && npm run build``.
+- To run the Python code: ``python main.py``.
+- Navigate to ``localhost:8765`` in your browser.
+
+Note
+----
+
+This file provides the Python code for interacting with the Jupyter notebook
+server using ``ZMQ`` and the ``tornado`` web server.
+
 """
 import re
 import subprocess
@@ -9,26 +28,35 @@ import threading
 
 import tornado.web
 
-# Install the pyzmq ioloop. This has to be done before anything else from
-# tornado is imported.
+# Install the pyzmq ioloop. Must be done after importing tornado.web and
+# before importing any additional tornado modules
 from zmq.eventloop import ioloop
 ioloop.install()
 
 PORT = 8765
+"""int: Port number of web application"""
 
 
 class MainPageHandler(tornado.web.RequestHandler):
+    """Handle requests between the main app page and notebook server."""
 
     def initialize(self, base_url):
+        """Intitialize the base URL of the handler."""
         self.base_url = base_url
 
     def get(self):
+        """Get the main page for the application's interface."""
         return self.render("index.html", static=self.static_url,
                            base_url=self.base_url)
 
 
 def main(argv):
+    """Start the 'console' example.
 
+    - Start the Tornado main event loop for the Jupyter notebook server
+    - Set up the main page event handler for the 'console' example
+
+    """
     url = "http://localhost:%s" % PORT
 
     nb_command = [sys.executable, '-m', 'notebook', '--no-browser', '--debug',
@@ -36,7 +64,7 @@ def main(argv):
     nb_server = subprocess.Popen(nb_command, stderr=subprocess.STDOUT,
                                  stdout=subprocess.PIPE)
 
-    # wait for notebook server to start up
+    # Wait for Jupyter notebook server to complete start up
     while 1:
         line = nb_server.stdout.readline().decode('utf-8').strip()
         if not line:
@@ -72,18 +100,18 @@ def main(argv):
     app = tornado.web.Application(handlers, static_path='build',
                                   template_path='.',
                                   compiled_template_cache=False)
-
     app.listen(PORT, 'localhost')
 
+    # For Windows, add no-op to wake every 5 seconds (5000 ms) to handle
+    # signals that may be ignored by the Tornado main event loop
     if sys.platform.startswith('win'):
-        # add no-op to wake every 5s
-        # to handle signals that may be ignored by the inner loop
         pc = ioloop.PeriodicCallback(lambda: None, 5000)
         pc.start()
 
     loop = ioloop.IOLoop.current()
     print('Browse to http://localhost:%s' % PORT)
     try:
+        # Start the Tornado main event loop
         loop.start()
     except KeyboardInterrupt:
         print(" Shutting down on SIGINT")

examples/filebrowser/main.py

@@ -1,6 +1,25 @@
 """
+An example demonstrating a stand-alone "filebrowser" example.
+
 Copyright (c) Jupyter Development Team.
 Distributed under the terms of the Modified BSD License.
+
+Example
+-------
+
+To run the example, make sure the Jupyter notebook server version 4.2+ is
+installed.
+
+- To build the JavaScript bundle: ``npm install && npm run build``.
+- To run the Python code: ``python main.py``.
+- Navigate to ``localhost:8765`` in your browser.
+
+Note
+----
+
+This file provides the Python code for interacting with the Jupyter notebook
+server using ``ZMQ`` and the ``tornado`` web server.
+
 """
 import re
 import subprocess
@@ -9,26 +28,35 @@ import threading
 
 import tornado.web
 
-# Install the pyzmq ioloop. This has to be done before anything else from
-# tornado is imported.
+# Install the pyzmq ioloop. Must be done after importing tornado.web and
+# before importing any additional tornado modules
 from zmq.eventloop import ioloop
 ioloop.install()
 
 PORT = 8765
+"""int: Port number of web application"""
 
 
 class MainPageHandler(tornado.web.RequestHandler):
+    """Handle requests between the main app page and notebook server."""
 
     def initialize(self, base_url):
+        """Intitialize the base URL of the handler."""
         self.base_url = base_url
 
     def get(self):
+        """Get the main page for the application's interface."""
         return self.render("index.html", static=self.static_url,
                            base_url=self.base_url)
 
 
 def main(argv):
+    """Start the 'filebrowser' example.
+
+    - Start the Tornado main event loop for the Jupyter notebook server
+    - Set up the main page event handler for the 'console' example
 
+    """
     url = "http://localhost:%s" % PORT
 
     nb_command = [sys.executable, '-m', 'notebook', '--no-browser', '--debug',
@@ -36,7 +64,7 @@ def main(argv):
     nb_server = subprocess.Popen(nb_command, stderr=subprocess.STDOUT,
                                  stdout=subprocess.PIPE)
 
-    # wait for notebook server to start up
+    # Wait for Jupyter notebook server to complete start up
     while 1:
         line = nb_server.stdout.readline().decode('utf-8').strip()
         if not line:
@@ -75,6 +103,8 @@ def main(argv):
 
     app.listen(PORT, 'localhost')
 
+    # For Windows, add no-op to wake every 5 seconds (5000 ms) to handle
+    # signals that may be ignored by the Tornado main event loop
     if sys.platform.startswith('win'):
         # add no-op to wake every 5s
         # to handle signals that may be ignored by the inner loop
@@ -84,6 +114,7 @@ def main(argv):
     loop = ioloop.IOLoop.current()
     print('Browse to http://localhost:%s' % PORT)
     try:
+        # Start the Tornado main event loop
         loop.start()
     except KeyboardInterrupt:
         print(" Shutting down on SIGINT")

tutorial/examples.md

@@ -0,0 +1,44 @@
+# Examples
+
+The `examples` directory in the JupyterLab repo contains:
+- several stand-alone examples (`console`, `filebrowser`,
+  `notebook`, `terminal`)
+- a more complex example (`lab`).
+
+Installation instructions for the examples are found in the project's
+README.
+
+After installing the jupyter notebook server 4.2+, follow the steps for
+installing the development version of JupyterLab. To build the examples,
+enter from the ``jupyterlab`` repo root directory: 
+
+    npm run server:examples
+
+To run a particular example, navigate to the example's subdirectory in the
+``examples`` directory and enter: 
+
+    python main.py
+
+##  Dissecting the 'filebrowser' example
+
+The filebrowser example provides a stand-alone implementation of a 
+filebrowser. Here's what the filebrowser's user interface looks like:
+
+![filebrowser user interface](filebrowser_example.png)
+
+Let's take a closer look at the source code in ``examples/filebrowser``.
+
+### Directory structure of 'filebrowser' example
+
+The filebrowser in ``examples/file`` is comprised by a handful of files and
+the ``src`` directory:
+
+![filebrowser source code](filebrowser_source.png)
+
+The filebrowser example has two key source files:
+
+- ``src/index.ts``: the TypeScript file that defines the functionality
+- ``main.py``: the Python file that enables the example to be run
+
+Reviewing the source code of each file will help you see the role that each
+file plays in the stand-alone filebrowser example.

tutorial/index.rst

@@ -7,7 +7,7 @@ JupyterLab Tutorial
 ===================
 
 .. important::
-    
+
     This is a very early pre-alpha developer preview and not suitable for
     general usage yet. Features and implementation are subject to change.
 
@@ -23,7 +23,8 @@ Contents:
    documents.md
    notebook.md
    patterns.md
-
+   examples.md
+   terminology.md
 
 Indices and tables
 ==================

tutorial/repo.md

@@ -19,9 +19,11 @@ Th npm package and the Python package are both named `jupyterlab`.
 
 ### Examples: `examples/`
 
-The `examples/` directory contains a few stand-alone examples of components in
-the package, such as a simple notebook on a page, a console, terminal,
-filebrowser, etc.
+The `examples/` directory contains stand-alone examples of components,
+such as a simple notebook on a page, a console, terminal, and a filebrowser.
+The `lab` example illustrates a simplified combination of components used in
+JupyterLab. This example shows multiple stand-alone components combined to
+create a more complex application.
 
 ### Testing: `test/`
 

tutorial/terminology.md

@@ -0,0 +1,16 @@
+# Terminology
+
+Learning to use a new technology and its architecture can be complicated by
+the jargon used to describe components. We provide this terminology guide
+to help smooth the learning the components.
+
+## Terms
+
+- Application
+- Extension
+- Phosphide
+- Phosphor
+- Provider: see Service Provider
+- Service Provider
+- Standalone example
+- TypeScript