[Buildbot-commits] buildbot/docs buildbot.texinfo,1.122,1.123

[Brian Warner]

Update of /cvsroot/buildbot/buildbot/docs
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv14518/docs

Modified Files:
	buildbot.texinfo 
Log Message:
[project @ docs: update docs on WebStatus, deprecate/deemphasize Waterfall]

Original author: warner at lothar.com
Date: 2007-09-30 08:28:57+00:00

Index: buildbot.texinfo
===================================================================
RCS file: /cvsroot/buildbot/buildbot/docs/buildbot.texinfo,v
retrieving revision 1.122
retrieving revision 1.123
diff -u -d -r1.122 -r1.123
--- buildbot.texinfo	30 Sep 2007 07:14:23 -0000	1.122
+++ buildbot.texinfo	30 Sep 2007 08:30:23 -0000	1.123
@@ -241,7 +241,6 @@
 
 Status Delivery
 
-* HTML Waterfall::              
 * WebStatus::                   
 * MailNotifier::                
 * IRC Bot::                     
@@ -250,8 +249,10 @@
 
 WebStatus
 
+* WebStatus Configuration Parameters::  
 * Buildbot Web Resources::      
 * XMLRPC server::               
+* HTML Waterfall::              
 
 Command-line tool
 
@@ -5909,11 +5910,11 @@
 @node Status Delivery, Command-line tool, Build Process, Top
 @chapter Status Delivery
 
-More details are available in the docstrings for each class, use
- at code{pydoc buildbot.status.html.Waterfall} to see them. Most status
-delivery objects take a @code{categories=} argument, which can contain
-a list of ``category'' names: in this case, it will only show status
-for Builders that are in one of the named categories.
+More details are available in the docstrings for each class, use a
+command like @code{pydoc buildbot.status.html.WebStatus} to see them.
+Most status delivery objects take a @code{categories=} argument, which
+can contain a list of ``category'' names: in this case, it will only
+show status for Builders that are in one of the named categories.
 
 (implementor's note: each of these objects should be a
 service.MultiService which will be attached to the BuildMaster object
@@ -5926,7 +5927,6 @@
 @file{buildbot/interfaces.py} for full details.)
 
 @menu
-* HTML Waterfall::              
 * WebStatus::                   
 * MailNotifier::                
 * IRC Bot::                     
@@ -5939,26 +5939,90 @@
 
 @c DOCUMENT THIS
 
- at node HTML Waterfall, WebStatus, Status Delivery, Status Delivery
- at section HTML Waterfall
 
- at cindex Waterfall
- at stindex buildbot.status.html.Waterfall
+ at node WebStatus, MailNotifier, Status Delivery, Status Delivery
+ at section WebStatus
+
+ at cindex WebStatus
+ at stindex buildbot.status.web.baseweb.WebStatus
+
+The @code{buildbot.status.html.WebStatus} status target runs a small
+web server inside the buildmaster. You can point a browser at this web
+server and retrieve information about every build the buildbot knows
+about, as well as find out what the buildbot is currently working on.
+
+The first page you will see is the ``Welcome Page'', which contains
+links to all the other useful pages. This page is simply served from
+the @file{public_html/index.html} file in the buildmaster's base
+directory, where it is created by the @command{buildbot create-master}
+command along with the rest of the buildmaster.
+
+The most complex resource provided by @code{WebStatus} is the
+``Waterfall Display'', which shows a time-based chart of events. This
+somewhat-busy display provides detailed information about all steps of
+all recent builds, and provides hyperlinks to look at individual build
+logs and source changes. By simply reloading this page on a regular
+basis, you will see a complete description of everything the buildbot
+is currently working on.
 
+There are also pages with more specialized information. For example,
+there is a page which shows the last 20 builds performed by the
+buildbot, one line each. Each line is a link to detailed information
+about that build. By adding query arguments to the URL used to reach
+this page, you can narrow the display to builds that involved certain
+branches, or which ran on certain Builders. These pages are described
+in great detail below.
+
+
+When the buildmaster is created, a subdirectory named
+ at file{public_html/} is created in its base directory. @code{WebStatus}
+will serve files from this directory: for example, when a user points
+their browser at the buildbot's @code{WebStatus} URL, they will see
+the contents of the @file{public_html/index.html} file. Likewise,
+ at file{public_html/robots.txt}, @file{public_html/buildbot.css}, and
+ at file{public_html/favicon.ico} are all useful things to have in there.
+The first time a buildmaster is created, the @file{public_html}
+directory is populated with some sample files, which you will probably
+want to customize for your own project. These files are all static:
+the buildbot does not modify them in any way as it serves them to HTTP
+clients.
 
 @example
-from buildbot.status import html
-w = html.Waterfall(http_port=8080)
-c['status'].append(w)
+from buildbot.status.html import WebStatus
+c['status'].append(WebStatus(8080))
 @end example
 
-The @code{buildbot.status.html.Waterfall} status target creates an
-HTML ``waterfall display'', which shows a time-based chart of events.
-This display provides detailed information about all steps of all
-recent builds, and provides hyperlinks to look at individual build
-logs and source changes. If the @code{http_port} argument is provided,
-it provides a strports specification for the port that the web server
-should listen on. This can be a simple port number, or a string like
+In addition, if you are familiar with twisted.web @emph{Resource
+Trees}, you can write code to add additional pages at places inside
+this web space. Just use @code{webstatus.putChild} to place these
+resources.
+
+The following section describes the special URLs and the status views
+they provide.
+
+
+ at menu
+* WebStatus Configuration Parameters::  
+* Buildbot Web Resources::      
+* XMLRPC server::               
+* HTML Waterfall::              
+ at end menu
+
+ at node WebStatus Configuration Parameters, Buildbot Web Resources, WebStatus, WebStatus
+ at subsection WebStatus Configuration Parameters
+
+The most common way to run a @code{WebStatus} is on a regular TCP
+port. To do this, just pass in the TCP port number when you create the
+ at code{WebStatus} instance; this is called the @code{http_port} argument:
+
+ at example
+from buildbot.status.html import WebStatus
+c['status'].append(WebStatus(8080))
+ at end example
+
+The @code{http_port} argument is actually a ``strports specification''
+for the port that the web server should listen on. This can be a
+simple port number, or a string like
 @code{tcp:8080:interface=127.0.0.1} (to limit connections to the
 loopback interface, and therefore to clients running on the same
 host)@footnote{It may even be possible to provide SSL access by using
@@ -5986,92 +6050,18 @@
 appear at @code{http://host/buildbot/}, and the right virtual host
 setup can even place it at @code{http://buildbot.host/} .
 
-Other arguments:
-
- at table @code
- at item allowForce
-If set to True (the default), then the web page will provide a ``Force
-Build'' button that allows visitors to manually trigger builds. This
-is useful for developers to re-run builds that have failed because of
-intermittent problems in the test suite, or because of libraries that
-were not installed at the time of the previous build. You may not wish
-to allow strangers to cause a build to run: in that case, set this to
-False to remove these buttons.
-
- at item favicon
-If set to a string, this will be interpreted as a filename containing
-a ``favicon'': a small image that contains an icon for the web site.
-This is returned to browsers that request the @code{favicon.ico} file,
-and should point to a .png or .ico image file. The default value uses
-the buildbot/buildbot.png image (a small hex nut) contained in the
-buildbot distribution. You can set this to None to avoid using a
-favicon at all.
-
- at item robots_txt
-If set to a string, this will be interpreted as a filename containing
-the contents of ``robots.txt''. Many search engine spiders request
-this file before indexing the site. Setting it to a file which
-contains:
- at example
-User-agent: *
-Disallow: /
- at end example
-will prevent most search engines from trawling the (voluminous)
-generated status pages.
-
- at end table
-
-
- at node WebStatus, MailNotifier, HTML Waterfall, Status Delivery
- at section WebStatus
-
- at cindex WebStatus
- at stindex buildbot.status.web.baseweb.WebStatus
-
-The Waterfall object is actually a subset of the views available with
-the more generalized @code{WebStatus} target. When you use
- at code{WebStatus}, you can put HTML files, CSS stylesheets, robots.txt,
-and other resources in a @file{public_html/} directory for use by the
-built-in webserver.
-
-When the buildmaster is created, a subdirectory named
- at file{public_html/} is created in its base directory. @code{WebStatus}
-will serve files from this directory: for example, when a user points
-their browser at the buildbot's @code{WebStatus} URL, they will see
-the contents of the @file{public_html/index.html} file. Likewise,
- at file{public_html/robots.txt} and @file{public_html/buildbot.css} are
-useful things to have in there. The first time a buildmaster is
-created, the @file{public_html} directory is populated with some
-sample files, which you will probably want to customize for your own
-project.
-
- at example
-from buildbot.status.html import WebStatus
-c['status'].append(WebStatus(8080))
- at end example
-
-Certain URL prefixes are handled specially by code within the
-buildbot. The pages available in these spaces provide various views into
-the buildbot status, each with a different focus. These pages can be
-configured further by adding query arguments, for example to restrict
-the page to only display certain Builders, or limit it to builds of a
-specific branch.
-
-In addition, if you are familiar with twisted.web @emph{Resource
-Trees}, you can write code to add additional pages at places inside
-this web space. Just use @code{webstatus.putChild} to place these
-resources.
-
-The following section describes the special URLs and the status views
-they provide.
+The other @code{WebStatus} argument is @code{allowForce}. If set to
+True, then the web page will provide a ``Force Build'' button that
+allows visitors to manually trigger builds. This is useful for
+developers to re-run builds that have failed because of intermittent
+problems in the test suite, or because of libraries that were not
+installed at the time of the previous build. You may not wish to allow
+strangers to cause a build to run: in that case, set this to False to
+remove these buttons. The default value is False.
 
 
- at menu
-* Buildbot Web Resources::      
-* XMLRPC server::               
- at end menu
 
- at node Buildbot Web Resources, XMLRPC server, WebStatus, WebStatus
+ at node Buildbot Web Resources, XMLRPC server, WebStatus Configuration Parameters, WebStatus
 @subsection Buildbot Web Resources
 
 Certain URLs are ``magic'', and the pages they serve are created by
@@ -6143,11 +6133,11 @@
 @file{/changes} for access to information about source code changes,
 etc.
 
- at item /builders/$BUILDERNAME/
+ at item /builders/$BUILDERNAME
 
 This describes the given Builder, and provides buttons to force a build.
 
- at item /builders/$BUILDERNAME/builds/$BUILDNUM/
+ at item /builders/$BUILDERNAME/builds/$BUILDNUM
 
 This describes a specific Build.
 
@@ -6167,6 +6157,22 @@
 settings were like. This maybe be useful for saving to disk and
 feeding to tools like 'grep'.
 
+ at item /changes
+
+This provides a brief description of the ChangeSource in use
+(@pxref{Change Sources}).
+
+ at item /changes/NN
+
+This shows detailed information about the numbered Change: who was the
+author, what files were changed, what revision number was represented,
+etc.
+
+ at item /buildslaves
+
+This summarizes each BuildSlave, including which Builders are
+configured to use it, whether the buildslave is currently connected or
+not, and host information retrieved from the buildslave itself.
 
 @item /one_line_per_build
 
@@ -6183,30 +6189,32 @@
 restrict the list. In addition, a @code{numbuilds=} argument will
 control how many lines are displayed (20 by default).
 
- at item /slave_status_timeline
+ at item /one_box_per_builder
 
-This provides a chronological display of configuration and operational
-events: master startup/shutdown, slave connect/disconnect, and
-config-file changes. When a config-file reload is abandoned because of
-an error in the config file, the error is displayed on this page.
+This page shows a small table, with one box for each Builder,
+containing the results of the most recent Build. It does not show the
+individual steps, or the current status. This is a simple summary of
+buildbot status: if this page is green, then all tests are passing.
 
-This page does not show any builds.
+As with @code{/one_line_per_build}, this page will also honor
+ at code{builder=} and @code{branch=} arguments.
 
+ at item /about
 
- at item /last_build
+This page gives a brief summary of the Buildbot itself: software
+version, versions of some libraries that the Buildbot depends upon,
+etc. It also contains a link to the buildbot.net home page.
 
-This shows one box per Builder, showing the results of the most recent
-complete build. It does not show the individual steps, or the current
-status.
+ at item /slave_status_timeline
 
-There are some options to limit the boxes displayed:
+(note: this page has not yet been implemented)
 
- at itemize @bullet
- at item
-branches: only show builds of specific branches
- at item only show specific builders
- at end itemize
+This provides a chronological display of configuration and operational
+events: master startup/shutdown, slave connect/disconnect, and
+config-file changes. When a config-file reload is abandoned because of
+an error in the config file, the error is displayed on this page.
 
+This page does not show any builds.
 
 @item /last_build/$BUILDERNAME/status.png
 
@@ -6229,7 +6237,7 @@
 
 @end table
 
- at node XMLRPC server,  , Buildbot Web Resources, WebStatus
+ at node XMLRPC server, HTML Waterfall, Buildbot Web Resources, WebStatus
 @subsection XMLRPC server
 
 When using WebStatus, the buildbot runs an XML-RPC server at
@@ -6238,9 +6246,56 @@
 using this interface.
 
 @table @code
+ at item getAllBuildsInInterval(start, stop)
+
+Return a list of builds that have completed after the 'start'
+timestamp and before the 'stop' timestamp. This looks at all Builders.
+
+The timestamps are integers, interpreted as standard unix timestamps
+(seconds since epoch).
+
+Each Build is returned as a tuple in the form: @code{(buildername,
+buildnumber, build_end, branchname, revision, results, text)}
+
+The buildnumber is an integer. 'build_end' is an integer (seconds
+since epoch) specifying when the build finished.
+
+The branchname is a string, which may be an empty string to indicate
+None (i.e. the default branch). The revision is a string whose meaning
+is specific to the VC system in use, and comes from the 'got_revision'
+build property. The results are expressed as a string, one of
+('success', 'warnings', 'failure', 'exception'). The text is a list of
+short strings that ought to be joined by spaces and include slightly
+more data about the results of the build.
+
+ at item getBuild(builder_name, build_number)
+
+Return information about a specific build.
+
+This returns a dictionary (aka ``struct'' in XMLRPC terms) with
+complete information about the build. It does not include the contents
+of the log files, but it has just about everything else.
 
 @end table
 
+ at node HTML Waterfall,  , XMLRPC server, WebStatus
+ at subsection HTML Waterfall
+
+ at cindex Waterfall
+ at stindex buildbot.status.html.Waterfall
+
+The @code{Waterfall} status target, deprecated as of 0.7.6, is a
+subset of the regular @code{WebStatus} resource (@pxref{WebStatus}).
+This section (and the @code{Waterfall} class itself) will be removed
+from a future release.
+
+ at example
+from buildbot.status import html
+w = html.Waterfall(http_port=8080)
+c['status'].append(w)
+ at end example
+
+
 
 @node MailNotifier, IRC Bot, WebStatus, Status Delivery
 @section MailNotifier