Merge lp:~rockstar/tarmac/tarmac-docs into lp:tarmac

[Paul Hummer]

Fix documentation bugs.

This branch fixes a bunch of documentation bugs that existed, and while I was at it, I fixed a few facepalm issues that mars discovered as he was messing with tarmac.

I basically removed all useful information from the README, and just pointed it to docs/introduction.txt. I did this because they were essentially saying the same thing.

[lp:~rockstar/tarmac/tarmac-docs]

384. By Paul Hummer on 2010-10-26

Fixed the cron job

[dobey (dobey)]

review: Approve

=== modified file 'README'
--- README	2009-07-11 04:18:18 +0000
+++ README	2010-10-26 01:04:00 +0000
@@ -1,53 +1,2 @@
-Introduction
-============
-
-The Tarmac Launchpad Branch Lander automatically lands branches for a project
-hosted on Launchpad after the merges have been properly approved.  It uses the
-Launchpad REST API to find approved merge proposals against the current
-development focus, and automatically merges those branches.
-
-
-Installation
-============
-
-Download the most recent Tarmac tarball or checkout the branch with ``bzr
-branch lp:tarmac``.  Within the tarmac directory, one can run ``tarmac-lander``
-straight from there, or run ``python setup.py install`` to install it to the
-system.
-
-
-Authentication
-==============
-
-When running Tarmac for the first time, it will need to get an OAuth token from
-Launchpad to allow it to act as a user.  One can do this by running the
-following command:
-
-  ``tarmac-authenticate``
-
-  ...and then follow the instructions.  The token will be placed in
-``$HOME/.config/tarmac/credentials``.  Tarmac does need to write some data, so
-it's required that the token have at least write access as the user.
-
-
-Usage
-=====
-
-Run ``tarmac-lander <project>`` to get Tarmac to look for the development
-focus of a project and any branches approved to merge into the branch.  One
-may test it out without merging by running:
-
-  ``tarmac-lander <project> --dry-run``
-
-Tarmac recognizes branches to land when the merge proposal's status (not the
-votes) is "Approved" and a valid commit message has been set for the branch.
-If a branch isn't being picked up by Tarmac to land, then one of these issues
-is probably the culprit.
-
-
-Web Interface
-=============
-
-Tarmac includes an optional web interface to display the status of Tarmac.
-The web interface is a wsgi app that can easily be loaded into mod_wsgi in
-your apache or nginx server, or run standalone.
+Tarmac is a script for merging bzr branches from launchpad.  It has many
+features.  To get started, please see docs/introduction.txt

=== modified file 'docs/introduction.txt'
--- docs/introduction.txt	2010-09-10 09:12:24 +0000
+++ docs/introduction.txt	2010-10-26 01:04:00 +0000
@@ -66,6 +66,41 @@
 If this directory or tree doesn't exist, Tarmac will go ahead and create it.
 
 
+Running Tarmac
+==============
+
+Once Tarmac is all configured, simply run ``tarmac merge``.  Voila!  If there
+are issues at all, you can run ``tarmac merge --debug`` to get more debug
+imformation.
+
+==============
+Tarmac on Cron
+==============
+
+Tarmac runs best on a cron, because it's doing stuff you shouldn't even need to
+worry about.  To make Tarmac run on a cron, add this to your crontab::
+
+0 1 * * * tarmac merge
+
+This will run Tarmac every hour, and merge branches if needed, and just quickly
+shut down if not needed.  Depending on the velocity of your project and what
+things Tarmac is doing when it merges (are your tests taking FOREVER?), you'll
+want to tune this to work best for your project.
+
+
+==========================
+Authenticating with Tarmac
+==========================
+
+If you ever feel the need to manually authenticate Tarmac, you can run::
+
+  tarmac authenticate
+
+Follow the prompts and you'll be ready to go.  Tarmac creates an authorization
+token in $HOME/.config/tarmac/credentials.  If this file is ever corrupted, you
+can just remove it and run the authentication again.
+
+
 ================
 Built-in Plugins
 ================
@@ -193,3 +228,11 @@
 system.  In order to install extra plugins, place them
 ``$HOME/.config/tarmac/plugins``.  They will then be available for import in
 python at tarmac.plugins.
+
+
+Getting Help
+============
+
+If you ever get stuck with Tarmac, you can easily find help by running::
+
+  tarmac help

=== modified file 'tarmac/bin/commands.py'
--- tarmac/bin/commands.py	2010-10-12 19:58:22 +0000
+++ tarmac/bin/commands.py	2010-10-26 01:04:00 +0000
@@ -33,6 +33,21 @@
         set_up_logging(self.config)
         self.logger = logging.getLogger('tarmac')
 
+    def _usage(self):
+        """Custom _usage for referencing "tarmac" instead of "bzr."""
+        s = 'tarmac ' + self.name() + ' '
+        for aname in self.takes_args:
+            aname = aname.upper()
+            if aname[-1] in ['$', '+']:
+                aname = aname[:-1] + '...'
+            elif aname[-1] == '?':
+                aname = '[' + aname[:-1] + ']'
+            elif aname[-1] == '*':
+                aname = '[' + aname[:-1] + '...]'
+            s += aname + ' '
+        s = s[:-1]
+        return s
+
     def run(self):
         '''Actually run the command.'''
 

=== modified file 'tarmac/bin/registry.py'
--- tarmac/bin/registry.py	2010-08-13 18:56:40 +0000
+++ tarmac/bin/registry.py	2010-10-26 01:04:00 +0000
@@ -19,6 +19,11 @@
 
     def _get_command(self, command, name):
         '''Return the command.'''
+        if name.startswith('-'):
+            if name == '--help':
+                name = 'help'
+            else:
+                return
         _command = None
         try:
             _command = self._registry[name]