Improve plugin documentation.

Signed-off-by: Edward Z. Yang <ezyang@mit.edu>

diff --git a/doc/create.rst b/doc/create.rst
index aaa88fc381e73abe156133f539a1d1440a077caf..e87726ee89b54b834466800e56ed77d99b5a776b 100644 (file)
--- a/doc/create.rst
+++ b/doc/create.rst
@@ -72,42 +72,52 @@ create :file:`$WIZARD/wizard/app/wordpress.py` and fill it in with a bare bones
 
 Finally, we have to tell Wizard about this new module.  If you are
 creating this new module for Scripts, the easiest way to tell Wizard
-about the application is to add it to the :mod:`wizard_scripts` plugin.
-You can do this by editing :file:`plugins/scripts/setup.py` and adding
-your application to the ``wizard.app`` entry point as follows::
-
-    'wizard.app': ['wordpress = wizard.app.wordpress:Application',
-                   'mediawiki = wizard.app.mediawiki:Application',
+about the application is to add it to the :mod:`wizard_scripts`
+`setuptools plugin <http://aroberge.blogspot.com/2008/12/plugins-part-6-setuptools-based.html>`_.
+EVen if you don't know anything about setuptools, it's pretty easy
+to add your application: edit the file  :file:`plugins/scripts/setup.py`
+and add your application to the ``wizard.app`` entry point by looking
+for the following chunk of code and adding a new line::
+
+    'wizard.app': ['mediawiki = wizard.app.mediawiki:Application',
                    'phpBB = wizard.app.phpBB:Application',
+                   'wordpress = wizard.app.wordpress:Application', # NEW LINE!
                   ],
 
-You can then refresh plugin information by running the :file:`refresh.sh`
+This tells Wizard that there is a new application named ``wordpress``,
+with a module named ``wizard.app.wordpress`` and a class named
+``Application`` in that module, which Wizard should use.
+
+You need to refresh plugin information by running the :file:`refresh.sh`
 script or by running :file:`python setup.py egg_info` in the
 :file:`plugins/scripts` directory.
 
-If you are creating this module separate from scripts, you will need to
-create a :file:`setup.py` file from scratch in your own plugin.  A
-reasonable template file is::
-
-    import setuptools
-
-    setuptools.setup(
-        name = 'wizard-myapp',
-        version = '0.1.dev',
-        author = 'Me',
-        author_email = 'my-email@mit.edu',
-        description = ('My Awesome Application'),
-        license = 'My Awesome License',
-        url = 'http://www.example.com/',
-        packages = setuptools.find_packages(),
-        entry_points = {
-            'wizard.app': ['wordpress = wizard.app.wordpress:Application',
-                          ],
-        }
-    )
-
-Don't forget to run :file:`python setup.py egg_info` and add your module
-to your :envvar:`PYTHON_PATH`.
+.. note::
+
+    If you do not want to place your application in the Scripts plugin,
+    you will need to create a :file:`setup.py` file from scratch in your
+    own plugin.  A reasonable template file is::
+
+        import setuptools
+
+        setuptools.setup(
+            name = 'wizard-myapp',
+            version = '0.1.dev',
+            author = 'Me',
+            author_email = 'my-email@mit.edu',
+            description = ('My Awesome Application'),
+            license = 'My Awesome License',
+            url = 'http://www.example.com/',
+            packages = setuptools.find_packages(),
+            entry_points = {
+                'wizard.app': ['wordpress = wizard.app.wordpress:Application',
+                              ],
+            }
+        )
+
+    Don't forget to run :file:`python setup.py egg_info` and add your module
+    to your :envvar:`PYTHON_PATH` (otherwise, Wizard won't know that
+    your plugin exists!)
 
 Now we are ready to put some code in our repository: the first thing we will
 add is the :term:`pristine` branch, which contains verbatim the code from upstream.