Backports for 5.0.0 and update changelog (#378)

* Fix index slice in ExtensionPointChangedEvent when plugin changes (#357) * Turn off macOS builds on Travis CI (#375) This PR turns off expensive macOS builds on Travis CI. We'll eventually use GitHub Actions to replace these. * update changelog with backported PRs * Make example run from any directory (#377) * Make it possible to run example scripts from anywhere. * Add a docstring for the test case * Add missing __init__.py * Import abcdefg... * Refactor documentation links to source on GitHub (#379) * Refactor external links to demo examples from extension_points.rst * Update links to github in introduction.rst * Refactor substitutions * Group substitutions * Update other references to github links * Flake8 * Remove two other links to github that point to TraitsGUI * Remove redundant newlines * Maintain all substituions in the same place * Remove two redundant lines * Contribute examples to etsdemo (#380) * remove logging from hello world and motd * remove logging from other examples * move examples into envisage * update the single URL in docs/conf.py * add examples as package_data * add entry point * flake8 * add demo folder and update package_data based off code review suggestion * Update docs/source/conf.py Co-authored-by: Kit Choi <[email protected]> * rename and add test for entry point * move GUI_Application example into envisage/examples * move old examples into envisage/examples/demo/legacy * Revert "move old examples into envisage/examples/demo/legacy" This reverts commit c026040. * move old examples into a new subdirectory called legacy * add a readme to reference new location for examples Co-authored-by: Kit Choi <[email protected]> * more changelog updates * more changes to changelog Co-authored-by: Kit Choi <[email protected]> Co-authored-by: Mark Dickinson <[email protected]>
enthought · Dec 2, 2020 · 511ba4a · 511ba4a
1 parent 127a98a
commit 511ba4a
Show file tree

Hide file tree

Showing 166 changed files with 366 additions and 312 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -25,8 +25,6 @@ env:
 matrix:
   include:
     - env: RUNTIME=3.6 TOOLKITS="null pyqt5 pyside2 wx"
-    - os: osx
-      env: RUNTIME=3.6 TOOLKITS="null pyqt5 pyside2 wx"
 
 cache:
   directories:

diff --git a/CHANGES.rst b/CHANGES.rst
@@ -7,10 +7,12 @@ Version 5.0.0
 
 Released: XXXX-XX-XX
 
-This is a major release mainly relating to code modernization.  In this
-release, support for Python versions <3.6 have been dropped.  The
+This is a major release mainly relating to code modernization. In this
+release, support for Python versions <3.6 have been dropped. The
 class_load_hooks and single_project modules have been removed. Additionally,
-there were various fixes to bugs, examples, tests, and documentation.
+there were various fixes to bugs, examples, tests, and documentation. Demo
+examples are also distributed as package data such that they are visible via
+the "etsdemo" GUI application (to be installed separately).
 
 Features
 --------
@@ -22,6 +24,7 @@ Features
 Fixes
 -----
 
+- Fix index slice in ExtensionPointChangedEvent when plugin changes (#357)
 - Fix ValueError from unregistering services when application stops (#345)
 - Fix the MOTD example (#319)
 - Fix the Hello_World example (#318)
@@ -31,6 +34,9 @@ Fixes
 Documentation
 -------------
 
+- Contribute examples to etsdemo (#380)
+- Refactor documentation links to source on GitHub (#379)
+- Make example run from any directory (#377)
 - Setup intersphinx in docs (#343)
 - Add documentation for envisage APIs (#340)
 - Use jinja templates for API documentation (#339)
@@ -63,6 +69,7 @@ Tests
 Build
 -----
 
+- Turn off macOS builds on Travis CI (#375)
 - Fix CI cron job setup to install apptools (#348)
 - Update setup.py to allow prerelease version (#344)
 - Add wx as being supported in etstool, add it back to CI, and test against

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -33,6 +33,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.extlinks",
     "sphinx.ext.githubpages",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
@@ -85,6 +86,39 @@
 # output. They are ignored by default.
 # show_authors = False
 
+# Substitutions reusable for all files.
+
+rst_epilog = """
+..
+   # substitutions for API objects
+
+.. |Application| replace:: :class:`~envisage.application.Application`
+.. |IApplication| replace:: :class:`~envisage.i_application.IApplication`
+.. |ExtensionPoint| replace:: :class:`~envisage.extension_point.ExtensionPoint`
+.. |Plugin| replace:: :class:`~envisage.plugin.Plugin`
+.. |IPlugin| replace:: :class:`~envisage.i_plugin.IPlugin`
+.. |envisage.api| replace:: :mod:`envisage.api`
+.. |envisage.ui.workbench| replace:: :mod:`envisage.ui.workbench.api`
+
+..
+   # substitutions for the Hello World example
+
+.. |Hello World| replace:: :github-demo:`Hello World <Hello_World/hello_world.py>`
+
+..
+   # substitutions for MOTD examples
+
+.. |acme.motd| replace:: :github-demo:`acme.motd <MOTD/acme/motd/motd_plugin.py>`
+.. |acme.motd.software_quotes| replace:: :github-demo:`acme.motd.software_quotes <MOTD/acme/motd/software_quotes/software_quotes_plugin.py>`
+.. |MOTD| replace:: :github-demo:`MOTD <MOTD/acme/motd/motd.py>`
+.. |IMOTD| replace:: :github-demo:`IMOTD <MOTD/acme/motd/i_motd.py>`
+.. |MOTDPlugin| replace:: :github-demo:`MOTDPlugin <MOTD/acme/motd/motd_plugin.py>`
+.. |MOTD run| replace:: :github-demo:`run.py <MOTD/run.py>`
+.. |IMessage| replace:: :github-demo:`IMessage <MOTD/acme/motd/i_message.py>`
+.. |Message| replace:: :github-demo:`Message <MOTD/acme/motd/message.py>`
+.. |messages.py| replace:: :github-demo:`message.py <MOTD/acme/motd/software_quotes/messages.py>`
+.. |Message of the Day| replace:: :github-demo:`Message of the Day <MOTD>`
+"""   # noqa: E501
 
 # Options for HTML output
 # -----------------------
@@ -193,3 +227,12 @@
     "traits": ("https://docs.enthought.com/traits", None),
     "traitsui": ("https://docs.enthought.com/traitsui", None),
 }
+
+
+# -- Options for extlinks extension -------------------------------------------
+
+extlinks = {
+    'github-demo': (
+        'https://github.com/enthought/envisage/tree/master/envisage/examples/demo/%s',   # noqa: E501
+        '')
+}
diff --git a/docs/source/envisage_core_documentation/extension_points.rst b/docs/source/envisage_core_documentation/extension_points.rst
@@ -2,7 +2,7 @@ Extension Points
 ================
 
 Whether or not we as software developers like to admit it, most (if not all) of
-the applications we write need to change over time. We fix bugs, and we add, 
+the applications we write need to change over time. We fix bugs, and we add,
 modify, and remove features. In other words, we spend most of our time either
 fixing or extending applications.
 
@@ -14,15 +14,15 @@ mechanism at each one. This makes it hard for developers who want to extend
 the application to know a) *where* they can add extensions, and b) *how*
 to add them.
 
-Envisage attempts to address this problem by admitting up front that 
+Envisage attempts to address this problem by admitting up front that
 applications need to be extensible, and by providing a standard way for
 developers to advertise the places where extension can occur (known as
 *extension points*), and for other developers to contribute *extensions* to
 them.
 
 In Envisage, extension points and the extensions contributed to them are stored
 in the *extension registry*. To see how extension points actually work, let's
-take a look at the `Message of the Day`_ example included in the Envisage
+take a look at the |Message of the Day| example included in the Envisage
 distribution. This example shows how to build a very simple application that
 prints a (hopefully witty, educational, or inspiring) "Message of the Day"
 chosen at random from a list of contributed messages.
@@ -32,12 +32,12 @@ Declaring an Extension Point
 
 Plugins declare their extension points in one of two ways:
 
-1) Declaratively - using the 'ExtensionPoint' trait type
+1) Declaratively - using the |ExtensionPoint| trait type
 2) Programmatically - by overriding the 'get_extension_points' method.
 
-In the MOTD example, the acme.motd_ plugin needs to advertise an extension
+In the MOTD example, the |acme.motd| plugin needs to advertise an extension
 point that allows other plugins to contribute new messages. Using the
-'ExtensionPoint' trait type, the plugin would look like this::
+|ExtensionPoint| trait type, the plugin would look like this::
 
     class MOTDPlugin(Plugin):
         """ The MOTD Plugin. """"
@@ -84,25 +84,25 @@ Either way, this tells us three things about the extension point:
 
 1) That the extension point is called "acme.motd.messages"
 2) That every item in a list of contributions to the extension point must
-   implement the IMessage_ interface.
+   implement the |IMessage| interface.
 3) That the extension point allows you to contribute messages!
 
 Making contributions to an Extension Point
 ------------------------------------------
 
-The `Message of the Day`_ example has a second plugin,
-acme.motd.software_quotes_ that contributes some pithy quotes about software
+The |Message of the Day| example has a second plugin,
+|acme.motd.software_quotes| that contributes some pithy quotes about software
 development to the application.
 
 First of all, we have to create the messages that we want to add. Remember that
-when the acme.motd_ plugin advertised the extension point, it told us that
-every contribution had to implement the IMessage_ interface. Happily, there is
-a class that does just that already defined for us (Message_) and so we create
-a simple module (messages.py_) and add our Message_ instances to it::
+when the |acme.motd| plugin advertised the extension point, it told us that
+every contribution had to implement the |IMessage| interface. Happily, there is
+a class that does just that already defined for us (|Message|) and so we create
+a simple module (|messages.py|) and add our |Message| instances to it::
 
     messages = [
         ...
-    
+
         Message(
             author = "Martin Fowler",
             text   = "Any fool can write code that a computer can understand. Good"
@@ -118,7 +118,7 @@ a simple module (messages.py_) and add our Message_ instances to it::
         ...
     ]
 
-Now we create a plugin for the acme.motd.software_quotes_ package and tell
+Now we create a plugin for the |acme.motd.software_quotes| package and tell
 Envisage about the messages that we have just created. Again there are are
 two ways that a plugin can do this:
 
@@ -186,14 +186,14 @@ event.
 Retrieving the contributions to an Extension Point
 --------------------------------------------------
 
-OK, here's where we are so far: One plugin (acme.motd_) has advertised the fact
+OK, here's where we are so far: One plugin (|acme.motd|) has advertised the fact
 that it has an extension point called "acme.motd.messages", and that the
-contributions to the extension point must implement the IMessage_ interface.
-Another plugin (acme.motd.software_quotes_) has kindly offered to contribute
+contributions to the extension point must implement the |IMessage| interface.
+Another plugin (|acme.motd.software_quotes|) has kindly offered to contribute
 some messages about software development. Now we need to know how to retrieve
 the contributed messages at runtime.
 
-In the MOTD example, the messages are retrieved by the acme.motd_ plugin::
+In the MOTD example, the messages are retrieved by the |acme.motd| plugin::
 
     class MOTDPlugin(Plugin):
         """ The MOTD Plugin. """"
@@ -223,15 +223,15 @@ In the MOTD example, the messages are retrieved by the acme.motd_ plugin::
             ...
 
 As you can see, all we have to do is to access the **messages** extension point
-trait when we create our instance of the MOTD_ class.
+trait when we create our instance of the |MOTD| class.
 
 This example demonstrates a common pattern in Envisage application development,
 in that contributions to extension points are most often used by plugin
 implementations to create and initialize services (in this case, an instance of
-the MOTD_ class).
+the |MOTD| class).
 
 The extension registry can also be accessed through the following method on the
-IApplication_ interface::
+|IApplication| interface::
 
     def get_extensions(self, extension_point):
         """ Return a list containing all contributions to an extension point.
@@ -245,31 +245,11 @@ extension point you would use::
 
     messages = application.get_extensions('acme.motd.messages')
 
-Note however, that using the ExtensionPoint_ trait type, adds the ability to
+Note however, that using the |ExtensionPoint| trait type, adds the ability to
 validate the contributions -- in this case, to make sure that they are all
-objects that implement (or can be adapted to) the IMessage_ interface. It also
+objects that implement (or can be adapted to) the |IMessage| interface. It also
 automatically connects the trait so that the plugin will receive trait change
 events if extensions are added/removed to/from the extension point at runtime.
 
 
 .. _`Python Eggs`: http://peak.telecommunity.com/DevCenter/PythonEggs
-
-.. _acme.motd: https://github.com/enthought/envisage/tree/master/examples/MOTD/acme/motd/motd_plugin.py
-
-.. _acme.motd.software_quotes: https://github.com/enthought/envisage/tree/master/examples/MOTD/acme/motd/software_quotes/software_quotes_plugin.py
-
-.. _ExtensionPoint: https://github.com/enthought/envisage/tree/master/envisage/extension_point.py
-
-.. _IApplication: https://github.com/enthought/envisage/tree/master/envisage/i_application.py
-
-.. _IMessage: https://github.com/enthought/envisage/tree/master/examples/MOTD/acme/motd/i_message.py
-
-.. _Message: https://github.com/enthought/envisage/tree/master/examples/MOTD/acme/motd/message.py
-
-.. _messages.py: https://github.com/enthought/envisage/tree/master/examples/MOTD/acme/motd/software_quotes/messages.py
-
-.. _`Message of the Day`: https://github.com/enthought/envisage/tree/master/examples/MOTD
-
-.. _MOTD: https://github.com/enthought/envisage/tree/master/examples/MOTD/acme/motd/motd.py
-
-.. _MOTDPlugin: https://github.com/enthought/envisage/tree/master/examples/MOTD/acme/motd/motd_plugin.py
diff --git a/docs/source/envisage_core_documentation/introduction.rst b/docs/source/envisage_core_documentation/introduction.rst
@@ -10,7 +10,7 @@ The project is really divided into 3 sub-projects:-
 
 1) Core_
 
-   The Envisage Core, found in the top-level envisage_ package,
+   The Envisage Core, found in the top-level |envisage.api| package,
    defines the basic application architecture including the plugin and
    extension mechanisms. All of the other sub-projects are simply collections
    of plugins that are built on top of the core.
@@ -23,7 +23,7 @@ The project is really divided into 3 sub-projects:-
    functionality commonly required in this type of application including
    actions, menubars, toolbars, user preferences, wizards etc. One of the most
    useful plugins in this project is the Workbench_ plugin (found in the
-   envisage.ui.workbench_ package) that helps you build a style of
+   |envisage.ui.workbench| package) that helps you build a style of
    user interface that is often (but not exclusively) found in integrated
    development environments (IDEs).
 
@@ -49,7 +49,7 @@ Getting Started
 ---------------
 
 The best way to get started is probably to take the time to read and digest the
-Core_ documentation and then work through the `Hello World`_ and
+Core_ documentation and then work through the |Hello World| and
 `Message of the Day`_ examples. Despite being extremely simple, the examples
 introduce you to *all* of the fundamental concepts of Envisage, and the *real*
 applications that you build (which will hopefully be a lot more useful) will be
@@ -67,9 +67,3 @@ documentation and examples first).
 .. _NetBeans: http://www.netbeans.org
 .. _OSGi: http://www.osgi.org
 .. _Workbench: Workbench.html
-
-.. _`Hello World`: https://github.com/enthought/envisage/tree/master/examples/Hello_World/hello_world.py
-
-.. _envisage: https://github.com/enthought/envisage/tree/master/envisage/api.py
-
-.. _envisage.ui.workbench: https://github.com/enthought/envisage/tree/master/envisage/ui/workbench/api.py