Merge lp://staging/~james-w/pkgme/add-docs into lp://staging/pkgme

Any chance of a review of this one too? Pretty please? :-)

Thanks,

James

=== modified file 'doc/backends/index.txt'
--- doc/backends/index.txt 2010-12-15 02:14:16 +0000
+++ doc/backends/index.txt 2010-12-23 23:56:44 +0000
> @@ -97,11 +97,71 @@
> Implementing a backend
> ----------------------
>
> -.. FIXME: Explain how to implement a backend
> -
> -
> -Information that pkgme may request
> -----------------------------------
> +A backend is a directory of scripts that are called by ``pkgme`` as needed.
> +
> +The name of the directory is the name of the backend, and should be unique.
> +
> +The first script that you need to provide is called ``want``, and is called to decide
> +if your backend should be used for the project in question. It is executed with the
> +current directory the root of the project, and should return a number on stdout that is
> +how well the backend will work for the project (see `Selecting a backend`_).
> +
> +After implementing that script you have a choice of how to provide the rest of the
> +information.
> +
> +Many scripts
> +~~~~~~~~~~~~
> +
> +You can provide one script per piece of information that ``pkgme`` may request.
> +The script is given the name of the piece of information that it will provide, and
> +is expected to print the information on stdout when invoked.

Do you have a list of the specific pieces of information that pkgme may
request? Maybe either enumerate them here or provide a cross-ref to the
page where they are defined.

> +
> +Each script may exit with an error if the information cannot be provided.
> +
> +The scripts are called with a current working directory of the root of the project,
> +and so should examine the files in the working directory to obtain the information.
> +
> +One script
> +~~~~~~~~~~
> +
> +It is also possible to write a single script that can provide multiple bits of
> +information at once. This script reads in JSON formatted description of the pieces
> +of information that are needed, and then writes a JSON formatted response on stdout
> +that contains the pieces of information.
> +
> +The script can exit with an error if no information can be provided, or may choose
> +to respond omitting the information that cannot be provided.
> +
> +The scripts is called with a current working directory of the root of the project,

s/scripts is/script is/

> +and so should examine the files in the working directory to obtain the information.
> +
> +The script may be called multiple times for the same project.
> +
> +The script should be called ``all_info``.
> +
> +``pkgme`` will write a JSON formatted list on the stdin of the ``all_info`` script
> +containing the names of the pieces of information that are desired. It is expected
> +to write a JSON formatted dict to its stdout and then exit. The dict should have keys
> +that are the names passed in to the script, and the values should be the required
> +information.
> +
> +For instance, if the script is passed::
> +
> + ["package_name", "version"]
> +
> +then it should respond with something like::
> +
> + {
> + "package_name": "foo",
> + "version": 1.0
> + }
> +
> +Keys may be omitted from the output if the information cannot be provided.
> +
> +Information that ``pkgme`` may request
> +---...

Approved, with a few minor comments.

On Mon, 24 Jan 2011 21:03:54 -0000, Barry Warsaw <email address hidden> wrote:
> Do you have a list of the specific pieces of information that pkgme may
> request? Maybe either enumerate them here or provide a cross-ref to the
> page where they are defined.

A forward reference is a good idea.

> > +The scripts is called with a current working directory of the root of the project,
>
> s/scripts is/script is/

Thanks.

James