From: Edward Z. Yang Date: Sat, 5 Jun 2010 20:28:29 +0000 (-0700) Subject: Update documentation. X-Git-Url: https://scripts.mit.edu/gitweb/wizard.git/commitdiff_plain/24663e53b03aae47fca82957038155d7717c0683 Update documentation. Signed-off-by: Edward Z. Yang --- diff --git a/API b/API deleted file mode 100644 index 26971f5..0000000 --- a/API +++ /dev/null @@ -1,28 +0,0 @@ -wizard install - Loads interactive autoinstaller. Users generally should use this. -wizard install --help - Help message, very basic, indicates: - - How to run the interactive installer - - How to specify an installation directory - - How to specify a specific application - - How to specify a specific version - - How to get help for that application -wizard install mediawiki - Installs MediaWiki application. Interactively asks for install - location and configuration. -wizard install mediawiki --help - Help message for that application. Show the configure message. - This is tricky, since just bouncing back wizard configure --help - will result in the wrong program name. Choices: - X Tell the user the appropriate command to get the correct help - choice. Poor because it makes them jump through an extra hoop, - however, once they have it makes "more sense" - This is the approach we'll take for now, before we make - ArgHandler work. - * Manually search replace the output of the configure command. - Hacky. - * Rewrite optparse to have a more robust %app substitution, - which includes being able to override it. Ehh... - X Manual help generation out of ArgHandler. Not bad, but requires - code to be written. - This is the correct solution, and should eventually be implemented. diff --git a/RELEASE b/RELEASE new file mode 100644 index 0000000..dc061ef --- /dev/null +++ b/RELEASE @@ -0,0 +1,21 @@ +Release plan +------------ + +The following things need to happen for Wizard to be released to the +outside world: + +* Scripts specific code needs to be fully factored out and placed + in a plugin. Check SCRIPTS for a full description. + +* Applications should also be moved to their own plugins. We need + to redevelop applications for the "general population" and make it + easy for hosting providers to customize these applications for + themselves without too much editing. It should also be easy for + people to use applications they care about, possibly running Python + off the internet. + + An interesting challenge will be to do the repository creation for + *all* versions of the application. + +* We need a website, even if it's just a spruced up version of the + Sphinx documentation. A logo would be nice too. diff --git a/SCRIPTS b/SCRIPTS index 59f1fc9..b270781 100644 --- a/SCRIPTS +++ b/SCRIPTS @@ -8,6 +8,12 @@ set up in a development type environment on a non-Scripts server. Here documents Scripts specific code inside Wizard that should be moved away: + * We store Wizard info inside .scripts/; this should really be + .wizard. This might be kind of crappy to change, though. Maybe + .scripts should still contain Scripts specific info, but we + should instantiate a .wizard directory automatically (which + should be ignored) that doesn't need to be created in repositories. + * wizard.scripts is the location that all Scripts specific code will eventually live. @@ -26,7 +32,11 @@ be moved away: * wizard.install contains strategies for guessing variables for an installation that are Scripts specific + * We should have `wizard install` do something intelligent about + prompting a user about possibilities; not everyone is going to + use the scripts-start wrapper. + * The mass-* commands are especially designed for Scripts, so while they're ostensibly portable, they'd probably need a bit of working - to be easy-to-use for other people. They also rely on a "versions" - directory whose code exists independently of Wizard. + to be easy-to-use for other people. They also rely on a + "versions" directory whose code exists independently of Wizard. diff --git a/TODO b/TODO index 4693d79..6aa9ad2 100644 --- a/TODO +++ b/TODO @@ -1,18 +1,16 @@ -The Git Autoinstaller +- [SCRIPTS] MediaWiki 1.9.3 and 1.6.7 -TODO NOW: +- Plugin-ify! Hook-ify! In more detail, applications should all be moved + out into plugins, scripts specific behavior should be moved into + plugins, and hooks need to be made available so that we can exert + the correct level of control. -- MediaWiki 1.9.3 and 1.6.7 - -- Plugin-ify! - -- Add support for mypristine workflow -- Wordpress needs to get rid of the siteurl hack, so that it actually - has a fully-qualified URL http://foo.scripts.mit.edu/blah. This will - also fix Wordpress's cron functionality. We should be careful not - to write over users who are on vhosts. We should figure out who is - still on twiddle paths. We should make sure the redirect is handled - correctly. +- [SCRIPTS] Wordpress needs to get rid of the siteurl hack, so that it + actually has a fully-qualified URL http://foo.scripts.mit.edu/blah. + This will also fix Wordpress's cron functionality. We should be + careful not to write over users who are on vhosts. We should figure + out who is still on twiddle paths. We should make sure the redirect + is handled correctly. - Remerges aren't reflected in the parent files, so `git diff` output is spurious. Not sure how to fix this w/o tree hackery. @@ -23,14 +21,14 @@ TODO NOW: - Parse output HTML for class="error" and give those errors back to the user (done), then boot them back into configure so they can enter in something different -- If you try to do an install on scripts w/o sql, it will sign you up but fail to write - the sql.cnf file. This sucks. +- [SCRIPTS] If you try to do an install on scripts w/o sql, it will sign + you up but fail to write the sql.cnf file. This sucks. -- Web application for installing autoinstalls has a hard problem - with credentials (as well as installations that are not conducted - on an Athena machine.) We have some crazy ideas involving a signed - Java applet that uses jsch to SSH into athena.dialup and perform - operations. +- [SCRIPTS] Web application for installing autoinstalls has a hard + problem with credentials (as well as installations that are not + conducted on an Athena machine.) We have some crazy ideas involving a + signed Java applet that uses jsch to SSH into athena.dialup and + perform operations. - Pay back code debt - Tidy up common code in callAsUser and drop_priviledges in shell; @@ -39,6 +37,7 @@ TODO NOW: output summary charts when I increase specificity - Other stuff + - Add support for mypristine workflow - Figure out why Sphinx sometimes fails to crossref :func: but wil crossref :meth:, even though the dest is very clearly a function. Example: :func:`wizard.app.php.re_var` @@ -55,14 +54,13 @@ TODO NOW: that gets installed in web_scripts and another directory that gets installed in Scripts. -- ACLs is a starting point for sending mail to users, but it has - several failure modes: +- [SCRIPTS] ACLs is a starting point for sending mail to users, but it + has several failure modes: - Old maintainers who don't care who are still on the ACL - - Private AFS groups that aren't mailing lists and that we - can't get to - A question is whether or not sending mail actually helps us: - many users will probably have to come back to us for help; many - other users won't care. + - Private AFS groups that aren't mailing lists and that we can't get + to A question is whether or not sending mail actually helps us: + many users will probably have to come back to us for help; many + other users won't care. [ XXX: metadata.rst ] diff --git a/doc/module/wizard.util.rst b/doc/module/wizard.util.rst index c20430b..b681647 100644 --- a/doc/module/wizard.util.rst +++ b/doc/module/wizard.util.rst @@ -34,6 +34,7 @@ Functions .. autofunction:: fetch .. autofunction:: mixed_newlines .. autofunction:: random_key +.. autofunction:: makedirs Exceptions ---------- diff --git a/wizard/app/__init__.py b/wizard/app/__init__.py index 8cf3521..0f80601 100644 --- a/wizard/app/__init__.py +++ b/wizard/app/__init__.py @@ -261,9 +261,8 @@ class Application(object): Takes a generic source checkout and parametrizes it according to the values of ``deployment``. This function operates on the current working directory. ``deployment`` should **not** be the same as the - current working directory. Default implementation uses - :attr:`parametrized_files` and a simple search and replace on those - files. + current working directory. See :meth:`parametrizeWithVars` for details + on the parametrization. """ # deployment is not used in this implementation, but note that # we do have the invariant the current directory matches @@ -271,6 +270,12 @@ class Application(object): variables = ref_deployment.extract() self.parametrizeWithVars(variables) def parametrizeWithVars(self, variables): + """ + Takes a generic source checkout and parametrizes it according to + the values of ``variables``. Default implementation uses + :attr:`parametrized_files` and a simple search and replace on + those files. + """ for file in self.parametrized_files: logging.debug("Parametrizing file '%s'\n" % (file, )) try: diff --git a/wizard/shell.py b/wizard/shell.py index d34740d..b8d4bd1 100644 --- a/wizard/shell.py +++ b/wizard/shell.py @@ -288,7 +288,7 @@ class ParallelShell(Shell): Blocking call that waits for an open subprocess slot. This is automatically called by :meth:`Shell.call`. """ - # XXX: This API sucks; the actuall call/callAsUser call should + # XXX: This API sucks; the actual call/callAsUser call should # probably block automatically (unless I have a good reason not to) # bail out immediately on initial ramp up if len(self.running) < self.max: return diff --git a/wizard/util.py b/wizard/util.py index c33d067..0cb607c 100644 --- a/wizard/util.py +++ b/wizard/util.py @@ -346,14 +346,17 @@ def soft_unlink(file): pass def makedirs(path): - """Create a directory path (a la mkdir -p or os.makedirs), - but don't complain if it already exists.""" + """ + Create a directory path (a la ``mkdir -p`` or ``os.makedirs``), + but don't complain if it already exists. + """ try: os.makedirs(path) - except OSError as exc: # Python >2.5 + except OSError as exc: if exc.errno == errno.EEXIST: pass - else: raise + else: + raise def fetch(host, path, subpath, post=None): try: