Move examples into documentation (#355)

* Move examples into the documentation, and add screenshots and brief descriptions * Remove examples directory * Update ci for new examples location * Remove more references to the removed 'examples' directory * Move the quick_start example code to the same place as the rest of the examples * Fix import order
enthought · Jul 2, 2021 · 55be7ca · 55be7ca
1 parent 7165120
commit 55be7ca
Show file tree

Hide file tree

Showing 15 changed files with 68 additions and 21 deletions.
diff --git a/.github/workflows/check-style.yml b/.github/workflows/check-style.yml
@@ -22,5 +22,4 @@ jobs:
       run: |
         python -m flake8
         python -m isort . --check --diff
-        python -m isort examples --check --diff
         python -m isort docs/source/guide/examples --check --diff
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -3,4 +3,3 @@ include MANIFEST.in
 include README.rst
 include DEVELOP.rst
 graft docs
-graft examples
diff --git a/ci/__main__.py b/ci/__main__.py
@@ -265,7 +265,7 @@ def example(edm, python_version, toolkit, example_name):
     Run one of the examples.
     """
     pyenv = _get_devenv(edm, python_version, toolkit)
-    example_script = os.path.join("examples", cfg.EXAMPLES[example_name])
+    example_script = cfg.EXAMPLES[example_name]
     pyenv.python([example_script])
 
 

diff --git a/ci/config.py b/ci/config.py
@@ -42,15 +42,15 @@
 # Location of repository root. Assumes that the ci script is being
 # run from the root of the repository.
 ROOT_DIR = os.path.abspath(".")
+EXAMPLES_DIR = os.path.join(ROOT_DIR, "docs", "source", "guide", "examples")
 PACKAGE_DIR = os.path.join(ROOT_DIR, PACKAGE_NAME)
 COVERAGE_DIR = os.path.join(ROOT_DIR, "coverage")
 
 # Directories containing isort configurations. We need to run isort
 # separately from each such directory.
 ISORT_ROOTS = [
     ROOT_DIR,
-    os.path.join(ROOT_DIR, "examples"),
-    os.path.join(ROOT_DIR, "docs", "source", "guide", "examples"),
+    EXAMPLES_DIR,
 ]
 
 # Locations of data directories for the ci package.
@@ -68,11 +68,11 @@
 # EDM configuration file.
 EDM_CONFIGURATION = os.path.join(DATA, "edm.yml")
 
-# Mapping from example names to script filenames.
+# Mapping from example names to example script paths.
 EXAMPLES = {
-    "squares": "slow_squares.py",
-    "pi": "pi_iterations.py",
-    "primes": "prime_counting.py",
+    "squares": os.path.join(EXAMPLES_DIR, "slow_squares.py"),
+    "pi": os.path.join(EXAMPLES_DIR, "pi_iterations.py"),
+    "primes": os.path.join(EXAMPLES_DIR, "prime_counting.py"),
 }
 
 # Python runtime versions.

diff --git a/docs/source/guide/examples.rst b/docs/source/guide/examples.rst
@@ -0,0 +1,56 @@
+..
+   (C) Copyright 2018-2021 Enthought, Inc., Austin, TX
+   All rights reserved.
+
+   This software is provided without warranty under the terms of the BSD
+   license included in LICENSE.txt and may be redistributed only under
+   the conditions described in the aforementioned license. The license
+   is also available online at http://www.enthought.com/licenses/BSD.txt
+
+   Thanks for using Enthought open source!
+
+Complete examples
+=================
+
+This section describes three complete examples, that make use of the
+three different background task types that Traits Futures currently supports.
+
+Slow squares
+------------
+
+.. image:: images/slow_squares.png
+   :alt: Screenshot of the slow squares GUI in action
+
+This :download:`example script <examples/slow_squares.py>` demonstrates a
+simple TraitsUI application that allows several background calculations to be
+running simultaneously, and displays the state of all previously submitted
+calculations in a table. Each "calculation" is a squaring operation; the
+calculation may fail randomly, with an increased chance of failure for larger
+inputs.
+
+.. literalinclude:: examples/slow_squares.py
+
+Prime counting
+--------------
+
+.. image:: images/prime_counting.png
+   :alt: Screenshot of the prime counting GUI in action
+
+This :download:`example script <examples/prime_counting.py>` demonstrates the
+:class:`~.ProgressFuture`, which reports progress information back to the
+GUI as the background computation progresses.
+
+.. literalinclude:: examples/prime_counting.py
+
+Approximating Pi
+----------------
+
+.. image:: images/pi_iterations.png
+   :alt: Screenshot of the π approximation GUI in action
+
+The final :download:`example <examples/pi_iterations.py>` uses the Chaco 2d
+plotting library and shows the use of the :class:`~.IterationFuture`.
+Successive approximations to π are computed and plotted, with the plot
+updated live with each new value reported by the background task.
+
+.. literalinclude:: examples/pi_iterations.py
diff --git a/examples/pi_iterations.py → docs/source/guide/examples/pi_iterations.py b/examples/pi_iterations.py → docs/source/guide/examples/pi_iterations.py
diff --git a/examples/prime_counting.py → docs/source/guide/examples/prime_counting.py b/examples/prime_counting.py → docs/source/guide/examples/prime_counting.py
diff --git a/docs/source/examples/quick_start.py → docs/source/guide/examples/quick_start.py b/docs/source/examples/quick_start.py → docs/source/guide/examples/quick_start.py
@@ -20,9 +20,8 @@
     Property,
     Str,
 )
-from traitsui.api import Item, UItem, View
-
 from traits_futures.api import CallFuture, submit_call, TraitsExecutor
+from traitsui.api import Item, UItem, View
 
 
 def slow_square(n):

diff --git a/examples/slow_squares.py → docs/source/guide/examples/slow_squares.py b/examples/slow_squares.py → docs/source/guide/examples/slow_squares.py
diff --git a/docs/source/guide/images/pi_iterations.png b/docs/source/guide/images/pi_iterations.png
diff --git a/docs/source/guide/images/prime_counting.png b/docs/source/guide/images/prime_counting.png
diff --git a/docs/source/guide/images/slow_squares.png b/docs/source/guide/images/slow_squares.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -51,11 +51,11 @@ Limitations
 Quick start
 -----------
 
-Here's a :download:`complete example <examples/quick_start.py>` showing a
+Here's a :download:`complete example <guide/examples/quick_start.py>` showing a
 minimal TraitsUI application that fires off a background computation when its
 "Calculate" button is pressed, and shows the result when it arrives.
 
-.. literalinclude:: examples/quick_start.py
+.. literalinclude:: guide/examples/quick_start.py
    :start-after: Thanks for using Enthought
    :lines: 2-
 
@@ -73,6 +73,7 @@ User Guide
    guide/toolkits.rst
    guide/testing.rst
    guide/advanced.rst
+   guide/examples.rst
 
 
 API Documentation

diff --git a/examples/.isort.cfg b/examples/.isort.cfg
diff --git a/setup.cfg b/setup.cfg
@@ -9,4 +9,4 @@ known_third_party = wx
 known_enthought = chaco,enable,pyface,traits,traitsui
 line_length = 79
 order_by_type = False
-skip_glob = docs/source/guide/examples/*,examples/*
+skip_glob = docs/source/guide/examples/*