Merge lp:~gary/launchpad/apidoc into lp:launchpad

[Gary Poster]

Fix the integration of the "Book" section of the apidoc.

This branch fixes the integration of the "Book" section of the apidoc.

In order to show its potential usefulness, I added a few files in the Launchpad tree that actually seemed like reasonably up-to-date documentation. I'm hoping we can expose some of the lazr.restful documents soon as well, and perhaps, when we make a static version of this, this can be a place to aggregate and publish the files in the tree that we actually consider to be documentation.

I fixed up some ReST in a fly-by, so that it would render nicely in the browser.

I also changed the apidoc-specific permissions to be a bit more careful: only allow them when we are in devmode. I considered moving them out to a separate module so that they could be grokked only when the apidoc zcml is parsed, but did not do it, both because of inertia and because of no clear location for such a file.

When I added a couple of module inclusions in the apidoc zcml, I reordered the includes to put the meta files first, as is usually done.

[Aaron Bentley (abentley)]

review: Approve

=== modified file 'configs/development/apidoc-configure-normal.zcml'
--- configs/development/apidoc-configure-normal.zcml	2010-07-23 19:17:41 +0000
+++ configs/development/apidoc-configure-normal.zcml	2010-07-26 19:26:46 +0000
@@ -69,15 +69,18 @@
     <!-- Turn on devmode for the following includes to work -->
     <meta:provides feature="devmode" />
 
-    <include package="zope.location" />
-    <include package="zope.app.applicationcontrol" />
-    <include package="zope.app.renderer" />
     <include package="zope.app.preference" file="meta.zcml" />
     <include package="zope.app.apidoc.codemodule" file="meta.zcml" />
     <include package="zope.app.apidoc.bookmodule" file="meta.zcml" />
+    <include package="zope.app.onlinehelp" file="meta.zcml" />
+
+    <include package="zope.app.apidoc" />
+    <include package="zope.app.applicationcontrol" />
+    <include package="zope.app.onlinehelp" />
     <include package="zope.app.preference" />
+    <include package="zope.app.renderer" />
     <include package="zope.app.tree" />
-    <include package="zope.app.apidoc" />
+    <include package="zope.location" />
 
     <apidoc:rootModule module="canonical" />
     <apidoc:rootModule module="lp" />
@@ -90,4 +93,33 @@
     <apidoc:rootModule module="bzrlib" />
     <apidoc:rootModule module="storm" />
 
+    <apidoc:bookchapter
+        id="lp"
+        title="Launchpad"
+        />
+    <apidoc:bookchapter
+        id="dbpolicy"
+        title="Storm Stores and Database Policies"
+        doc_path="../../lib/canonical/launchpad/doc/db-policy.txt"
+        parent="lp"
+        />
+    <apidoc:bookchapter
+        id="memcachetales"
+        title="Memcache Tales Expressions"
+        doc_path="../../lib/lp/services/memcache/doc/tales-cache.txt"
+        parent="lp"
+        />
+    <apidoc:bookchapter
+        id="sprites"
+        title="Image Sprites"
+        doc_path="../../lib/lp/services/doc/sprites.txt"
+        parent="lp"
+        />
+    <apidoc:bookchapter
+        id="buildout"
+        title="Buildout"
+        doc_path="../../doc/buildout.txt"
+        parent="lp"
+        />
+
 </configure>

=== modified file 'lib/canonical/launchpad/security.py'
--- lib/canonical/launchpad/security.py	2010-07-26 19:13:49 +0000
+++ lib/canonical/launchpad/security.py	2010-07-26 19:26:46 +0000
@@ -11,6 +11,7 @@
 from zope.interface import implements, Interface
 from zope.component import getAdapter, getUtility
 
+from canonical.config import config
 from canonical.launchpad.interfaces.account import IAccount
 from canonical.launchpad.interfaces.emailaddress import IEmailAddress
 from canonical.launchpad.interfaces.librarian import (
@@ -1087,10 +1088,12 @@
     usedfor = Interface
 
     def checkUnauthenticated(self):
-        return True
+        # We only want this permission to work at all for devmode.
+        return config.devmode
 
     def checkAuthenticated(self, user):
-        return True
+        # We only want this permission to work at all for devmode.
+        return config.devmode
 
 
 class ManageApplicationForEverybody(UseApiDoc):
@@ -1103,6 +1106,16 @@
     usedfor = Interface
 
 
+class ZopeViewForEverybody(UseApiDoc):
+    """This is just to please apidoc.launchpad.dev.
+
+    We do this because zope.app.apidoc uses that permission, but nothing else
+    should be using it.
+    """
+    permission = 'zope.View'
+    usedfor = Interface
+
+
 class OnlyBazaarExpertsAndAdmins(AuthorizationBase):
     """Base class that allows only the Launchpad admins and Bazaar
     experts."""

=== modified file 'lib/lp/services/doc/sprites.txt'
--- lib/lp/services/doc/sprites.txt	2010-02-11 04:55:23 +0000
+++ lib/lp/services/doc/sprites.txt	2010-07-26 19:26:46 +0000
@@ -6,13 +6,15 @@
 view a page. An individual sprite is displayed as a background image
 on an element by setting the background position.
 
-A new image can be added to the combined file with the command:
+A new image can be added to the combined file with the command::
+
     make sprite_image
 
 The resulting icon-sprites and icon-sprites.positioning files must
 be committed to the repository. Any changes to the CSS template will
 be automatically picked up when Launchpad is restarted. If you don't
-want to restart launchpad.dev, you can run:
+want to restart launchpad.dev, you can run::
+
     make css_combine
 
 
@@ -23,11 +25,15 @@
 indicating that the background-image for a given rule should be
 added to the combined image file and the rule should be updated.
 
-For example:
+For example::
+
     .add {
         background-image: url(/@@/edit.png); /* sprite-ref: group1 */
     }
+
 would become
+::
+
     .add {
         background-image: url(foo/combined_image.png);
         background-position: 0px 234px;