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

[James Westby]

Hi,

Here are some improvements to the docs for backend authors,
notably trying to explain how to implement a backend.

Thanks,

James

[James Westby (james-w)]

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

Thanks,

James

[Barry Warsaw (barry)]

=== 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
> +---...

review: Approve

[Barry Warsaw (barry)]

Approved, with a few minor comments.

[James Westby (james-w)]

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

[lp:~james-w/pkgme/add-docs]

44. By James Westby on 2011-02-05

Tweaks from review. Thanks Barry.

=== modified file 'doc/backends/index.txt'
--- doc/backends/index.txt	2010-12-15 02:14:16 +0000
+++ doc/backends/index.txt	2011-02-05 21:06:31 +0000
@@ -1,8 +1,8 @@
-==============
-pkgme backends
-==============
+==================
+``pkgme`` backends
+==================
 
-pkgme backends provide the project specific information that is needed to generate
+``pkgme`` backends provide the project specific information that is needed to generate
 the packaging. They examine the project in question and provide the information to
 the best of their ability.
 
@@ -13,7 +13,7 @@
 How they work
 -------------
 
-pkgme itself is agnostic about the type of project that it is working on, but knows
+``pkgme`` itself is agnostic about the type of project that it is working on, but knows
 how to put information about a project in to the packaging files such that result
 should work, assuming that the information provided is good enough.
 
@@ -22,13 +22,13 @@
 project.
 
 In this manner, the backends, and so you as a backend author, don't need to know
-much about packaging, and pkgme doesn't need to know about every different sort of
+much about packaging, and ``pkgme`` doesn't need to know about every different sort of
 project that there is.
 
 Selecting a backend
 -------------------
 
-When pkgme is asked to create the packaging for a project, it firsts selects the
+When ``pkgme`` is asked to create the packaging for a project, it firsts selects the
 backend that is most suited to the task. To do this it asks each backend to report
 a score of how well it thinks that it can handle that project.
 
@@ -59,7 +59,7 @@
 Getting the info
 ----------------
 
-When pkgme needs to get a bit of information about the project, such as its name, or
+When ``pkgme`` needs to get a bit of information about the project, such as its name, or
 the dependencies required to build, it asks the backend that it selected. The backend
 is expected to do its best to provide that information, but not to provide it if it can't
 do so, otherwise the generated packaging wouldn't work.
@@ -74,18 +74,18 @@
 
 The first of these is in the specification of the build dependencies, where the backend
 has to provide the list of packages that are needed. While the backend probably has
-available the list of modules used or similar, it wouldn't be possible for pkgme to
+available the list of modules used or similar, it wouldn't be possible for ``pkgme`` to
 translate these to a list of packages while remaining generic.
 
 Therefore one of the things the backend must be able to do is to go from the list of
 modules to the list of packages that provide them, using whatever means is appropriate.
 
 The second area where the backend needs to know something related to packaging is specifying
-what build system to use. pkgme leaves all the steps of actually building the package, knowing
+what build system to use. ``pkgme`` leaves all the steps of actually building the package, knowing
 what commands to run to build, what files to put where, up to debhelper. debhelper in turn
-delegates some of this work to its buildsystems, which are analogous to pkgme's backends.
+delegates some of this work to its buildsystems, which are analogous to ``pkgme``'s backends.
 
-Therefore pkgme needs to know which buildsystem to instruct debhelper to use, and for this it
+Therefore ``pkgme`` needs to know which buildsystem to instruct debhelper to use, and for this it
 will query the backend. This means that the backend should know which debhelper buildsystem
 is appropriate for the project. If you are implementing a backend for which there isn't yet
 a debhelper buildsystem, you will also have to implement that in order to enjoy completely
@@ -97,11 +97,72 @@
 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. See
+`Information that ``pkgme`` may request`_.
+
+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 script is 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.
+
+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
+--------------------------------------
+
+The following are the bits of information that your backend may be requested to provide.
 
 .. This outputs information on the info that a backend can provide, based
    on introspecting the code. See pkgme.rstinfo for the code that does