Fix documentation bugs due to plugin system.

[wizard.git] / doc / create.rst

diff --git a/doc/create.rst b/doc/create.rst
index 6dc2754cd678d17758fd82ba234ec8f2b4a0aba7..6b25e145aba972704f14c21442967c17ab5799cb 100644 (file)
--- a/doc/create.rst
+++ b/doc/create.rst
@@ -39,9 +39,15 @@ Pristine
 --------
 
 This is a tutorial centered around creating a `Wordpress <http://wordpress.org/>`_
 --------
 
 This is a tutorial centered around creating a `Wordpress <http://wordpress.org/>`_

-repository.  For the sake of demonstration,
-we shall assume that this repository hasn't been created yet.
-The repository then doesn't exist, we should create it::
+repository.  It assumes you have an upstream; if you do not,
+you can skip most of these steps: just ensure you have a Git repository
+which contains a :term:`pristine` and :term:`master` branch,
+as well as tags for all of the releases in the form ``appname-1.2.3``
+and ``appname-1.2.3-scripts``.
+
+For the sake of demonstration, we shall assume that this repository
+hasn't been created yet.  The repository then doesn't exist, we should
+create it::

 
     cd "$WIZARD/srv"
     mkdir wordpress
 
     cd "$WIZARD/srv"
     mkdir wordpress


@@ -64,6 +70,45 @@ create :file:`$WIZARD/wizard/app/wordpress.py` and fill it in with a bare bones
     class Application(app.Application):
         pass
 
     class Application(app.Application):
         pass
 

+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',
+                   'phpBB = wizard.app.phpBB:Application',
+                  ],
+
+You can then 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 :env:`PYTHON_PATH`.
+

 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.
 


@@ -141,14 +186,7 @@ First things first: verify that we are on the master branch::
 
         patch -n0 < /mit/scripts/deploy/wordpress-2.0.2/wordpress.patch
 
 
         patch -n0 < /mit/scripts/deploy/wordpress-2.0.2/wordpress.patch
 

-Then, run the following command to setup a :file:`.scripts` directory::
-
-    wizard prepare-new
-
-This directory holds Wizard related files, and is also used by
-:command:`parallel-find.pl` to determine if a directory is an autoinstall.
-
-Finally, if you are running a PHP application, you'll need to setup
+If you are running a PHP application, you'll need to setup

 a :file:`php.ini` and symlinks to it in all subdirectories.
 As of November 2009, all PHP applications load the same :file:`php.ini` file;
 so just grab one from another of the PHP projects.  We'll rob our own
 a :file:`php.ini` and symlinks to it in all subdirectories.
 As of November 2009, all PHP applications load the same :file:`php.ini` file;
 so just grab one from another of the PHP projects.  We'll rob our own


@@ -156,6 +194,7 @@ crib in this case::
 
     cp /mit/scripts/deploy/php.ini/wordpress php.ini
     athrun scripts fix-php-ini
 
     cp /mit/scripts/deploy/php.ini/wordpress php.ini
     athrun scripts fix-php-ini

+    git add .

 
 Now commit, but don't get too attached to your commit; we're going
 to be heavily modifying it soon::
 
 Now commit, but don't get too attached to your commit; we're going
 to be heavily modifying it soon::


@@ -166,16 +205,29 @@ Installation
 ------------
 
 We now need to make it possible for a user to install the application.
 ------------
 
 We now need to make it possible for a user to install the application.

-Most web applications have a number of web scripts for generating a
-configuration file, so creating the install script involves:
+The :meth:`~wizard.install.Application.install` method should take the
+application from a just cloned working copy into a fully functioning web
+application with configuration and a working database, etc.  Most web
+applications have a number of web scripts for generating a configuration
+file, so creating the install script tend to involve:
+
+
+    1. Deleting any placeholder files that were in the repository (there
+       aren't any now, but there will be soon.)

 
 

-    1. Determining what input values you will need from the user, such
+    2. Determining what input values you will need from the user, such

        as a title for the new application or database credentials; more
        on this shortly.
 
        as a title for the new application or database credentials; more
        on this shortly.
 

-    2. Determining what POST values need to be sent to what URLs.
-       Since you're converting a repository, this job is even simpler: you just
-       need to port the Perl script that was originally used into Python.
+    3. Determining what POST values need to be sent to what URLs or to
+       what shell scripts (these are the install scripts the application
+       may have supplied to you.)
+
+.. supplement:: Conversions
+
+    Since you're converting a repository, this job is even simpler: you
+    just need to port the Perl script that was originally used into
+    Python.

 
 There's an in-depth explanation of named input values in
 :mod:`wizard.install`.  The short version is that your application
 
 There's an in-depth explanation of named input values in
 :mod:`wizard.install`.  The short version is that your application


@@ -216,11 +268,6 @@ Some tips and tricks for writing :meth:`wizard.app.Application.install`:
       consequently be queried.  For convenience, we've bound metadata
       to the connection, you can perform implicit execution.
 
       consequently be queried.  For convenience, we've bound metadata
       to the connection, you can perform implicit execution.
 

-.. todo::
-
-    Our installer needs to also parametrize :file:`php.ini`, which we haven't
-    done yet.
-

 To test if your installation function works, it's probably convenient to
 create a test script in :file:`tests`; :file:`tests/test-install-wordpress.sh`
 in the case of Wordpress.  It will look something like::
 To test if your installation function works, it's probably convenient to
 create a test script in :file:`tests`; :file:`tests/test-install-wordpress.sh`
 in the case of Wordpress.  It will look something like::


@@ -444,6 +491,11 @@ commit with these changes and force them back into the public repository::
     git commit --amend -a
     git push --force
 
     git commit --amend -a
     git push --force
 

+You should test again if your install script works; it probably doesn't,
+since you now have a configuration file hanging around.  Use
+:func:`wizard.util.soft_unlink` to remove the file at the very beginning
+of the install process.
+

 Ending ceremonies
 -----------------
 
 Ending ceremonies
 -----------------