Improve plugin documentation.

[wizard.git] / doc / create.rst

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
 
 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',
                    '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.
 
 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.
 
 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.