Merge ~cjwatson/launchpad:db-fix-doc-running into launchpad:db-devel

[Colin Watson]

Manually merge from master to fix TestSphinxDocumentation

[Ioana Lasc (ilasc)]

review: Approve

diff --git a/doc/index.rst b/doc/index.rst
index 1677578..2fa2b59 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -47,7 +47,9 @@ Technical
 .. toctree::
    :maxdepth: 1
 
+   running-details
    pip
+   security
 
 Possibly out-of-date
 --------------------
@@ -55,7 +57,6 @@ Possibly out-of-date
 .. toctree::
    :maxdepth: 1
 
-   security
    email
 
 Other
diff --git a/doc/security.rst b/doc/security.rst
index 0ff5d6a..c80dba8 100644
--- a/doc/security.rst
+++ b/doc/security.rst
@@ -10,20 +10,24 @@ This document is about security policy in Launchpad.
 Defining Permissions in Launchpad
 ---------------------------------
 
-**NOTE: A new permission should only be defined if absolutely necessary, and
-it should be considered thoroughly in a code review.**
+.. note::
 
-Occassionally, you'll find yourself in a situation where the existing
-permissions in Launchpad aren't enough for what you want. For example, as I
-was writing this document I needed a permission I could attach to things to
-provide policy for who can view a thing. That is, I wanted a permission called
-launchpad.View.
-A new permission (see the NOTE above) is defined in Launchpad in the file
-lib/canonical/launchpad/permissions.zcml. So, to define the permission
-launchpad.View, we'd add a line like this to that file:
+    A new permission should only be defined if absolutely necessary, and it
+    should be considered thoroughly in a code review.
 
-    <permission id="launchpad.View" title="Viewing something"
-      access_level="read" />
+Occasionally, you'll find yourself in a situation where the existing
+permissions in Launchpad aren't enough for what you want. For example, when
+privacy support was first being added to Launchpad, it required a permission
+to provide policy for who can view a thing, called ``launchpad.View``.
+
+A new permission (see the note above) is defined in Launchpad in the file
+``lib/lp/permissions.zcml``. So, to define the permission
+``launchpad.View``, we'd add a line like this to that file:
+
+.. code-block:: xml
+
+    <permission
+      id="launchpad.View" title="Viewing something" access_level="read" />
 
 
 Defining Authorization Policies for Permissions
@@ -36,25 +40,29 @@ interface.
 In Launchpad, an authorization policy is expressed through a security adapter.
 To define a security adapter for a given permission on an interface:
 
-1. Define the adapter in lib/canonical/launchpad/security.py. Here's a simple
-example of an adapter that authorizes only an object owner for the
-launchpad.Edit permission on objects that implement the IHasOwner interface::
+1. Define the adapter in ``lib/lp/security.py``. Here's a simple example of
+   an adapter that authorizes only an object owner for the
+   ``launchpad.Edit`` permission on objects that implement the ``IHasOwner``
+   interface:
+
+.. code-block:: python
 
     class EditByOwner(AuthorizationBase):
         permission = 'launchpad.Edit'
         usedfor = IHasOwner
 
-        def checkAuthenticated(self, person):
+        def checkAuthenticated(self, user):
             """Authorize the object owner."""
-            if person.id == self.obj.owner.id:
-                return True
+            return user.isOwner(self.obj)
+
+Read the ``IAuthorization`` interface to ensure that you've defined the
+adapter appropriately.
 
-Read the IAuthorization interface to ensure that you've defined the adapter
-appropriately.
+2. Declare the permission on a given interface in a ZCML file. So, for the
+   above adapter, here's how it might be hooked up to ``IProduct``, where
+   ``IProduct`` is protected with the ``launchpad.Edit`` permission:
 
-2. Declare the permission on a given interface in a zcml file. So, for the
-above adapter, here's how it's hooked up to IProduct, where IProduct is
-protected with the launchpad.Edit permission::
+.. code-block:: xml
 
     <class
         class="lp.registry.model.product.Product">
@@ -68,6 +76,7 @@ protected with the launchpad.Edit permission::
           set_attributes="commercial_subscription description"/>
     </class>
 
-In this example, the EditByOwner adapter's checkAuthenticated method will be
-called to determine if the currently authenticated user is authorized to
-access whatever is protected by launchpad.Edit on an IProduct.
+In this example, the ``EditByOwner`` adapter's ``checkAuthenticated`` method
+will be called to determine if the currently authenticated user is
+authorized to access whatever is protected by ``launchpad.Edit`` on an
+``IProduct``.