Merge lp:~leonardr/lazr.restful/version-descriptions into lp:lazr.restful

[Leonard Richardson]

This branch adds two new attributes to web service configuration, "service_description" and "version_descriptions". "service_description" is supposed to be a human-readable overview of the web service; version_descriptions is a map of version names to human-readable overviews of what makes that version different.

Both attributes are put into <doc> tags in the generated WADL. For my next trick, I'll pull them out of the WADL and incorporate them into the generated Launchpad API documentation.

[Gary Poster (gary)]

merge-conditional

Thank you

Gary

[2:46pm] gary_poster: leonardr: "[x for x in contents['service_doc']]" -> "list(contents['service_doc']]" ?
[2:47pm] gary_poster: leonardr: lines 189 and 191 of diff
[2:47pm] leonardr: gary: sure
[2:47pm] gary_poster: cool
[2:48pm] gary_poster: leonardr: do you intend to keep pdb around? line 286
[2:48pm] leonardr: gary, no, that's in by mistake
[2:48pm] gary_poster: cool
[2:49pm] gary_poster: leonardr: otherwise, r=gary. Will mark as such.
[2:49pm] leonardr: gary: also the mssing = object() needs to go
[2:49pm] gary_poster: ah, ok. Should have investigated more carefully then.

review: Approve

[lp:~leonardr/lazr.restful/version-descriptions]

126. By Leonard Richardson on 2010-03-10

Response to feedback.

=== modified file 'src/lazr/restful/NEWS.txt'
--- src/lazr/restful/NEWS.txt	2010-03-03 13:08:12 +0000
+++ src/lazr/restful/NEWS.txt	2010-03-10 20:48:29 +0000
@@ -5,6 +5,14 @@
 Development
 ===========
 
+There are two new attributes of the web service configuratino,
+"service_description" and "version_descriptions". Both are optional,
+but they're useful for giving your users an overview of your web
+service and of the differences between versions.
+
+0.9.22 (2010-03-05)
+===================
+
 Special note: this version will break backwards compatibility in your
 web service unless you take a special step. See
 "last_version_with_named_mutator_operations" below.

=== modified file 'src/lazr/restful/example/base/root.py'
--- src/lazr/restful/example/base/root.py	2010-02-25 17:07:16 +0000
+++ src/lazr/restful/example/base/root.py	2010-03-10 20:48:29 +0000
@@ -385,12 +385,19 @@
 
 class WebServiceConfiguration(BaseWebServiceConfiguration):
     directives.publication_class(WebServiceTestPublication)
-    code_revision='test.revision'
-    default_batch_size=5
-    hostname='cookbooks.dev'
-    match_batch_size=50
-    active_versions=['1.0', 'devel']
-    last_version_with_mutator_named_operations=None
-    use_https=False
-    view_permission='lazr.restful.example.base.View'
+    code_revision = 'test.revision'
+    default_batch_size = 5
+    hostname = 'cookbooks.dev'
+    match_batch_size = 50
+    active_versions = ['1.0', 'devel']
+    service_description = """<p>This is a web service.</p>
+    <p>It's got resources!</p>"""
+    version_descriptions = { 'devel' : """<p>The unstable development
+    version.</p>
+
+    <p>Don't use this unless you like changing things.</p>"""
+                             }
+    last_version_with_mutator_named_operations = None
+    use_https = False
+    view_permission = 'lazr.restful.example.base.View'
 

=== modified file 'src/lazr/restful/example/base/tests/wadl.txt'
--- src/lazr/restful/example/base/tests/wadl.txt	2010-02-15 14:56:36 +0000
+++ src/lazr/restful/example/base/tests/wadl.txt	2010-03-10 20:48:29 +0000
@@ -6,7 +6,6 @@
 format. These documents are similar to the HTML documents that provide
 human beings with links to click and forms to fill out.
 
-===============
 Entry resources
 ===============
 
@@ -103,7 +102,6 @@
 document that says "The resource at this URL is of type [foo]," where
 [foo] is a reference to another WADL document.
 
-====================
 Collection resources
 ====================
 
@@ -137,7 +135,6 @@
     >>> resource.attrib['type']
     'http://...#cookbooks'
 
-===========================
 Scoped collection resources
 ===========================
 
@@ -165,7 +162,6 @@
     >>> resource.attrib['type']
     'http://...#recipe-page-resource'
 
-=====================
 Hosted file resources
 =====================
 
@@ -224,7 +220,6 @@
     >>> resource.attrib['type']
     'http://...#HostedFile'
 
-================
 The service root
 ================
 
@@ -257,19 +252,41 @@
 located here are the descriptions of the JSON representations those
 resources serve.
 
-======================================
-Description of the service root itself
-======================================
-
-Let's whittle down the complexity a little by taking a look at the
-description of the service root resource itself.
+Description of the full service
+--------------------------------
+
+The first two tags in the WADL file are human-readable documentation
+for the entire web service.
+
 
     >>> from lxml.etree import _Comment
     >>> children = [child for child in tree
     ...             if not isinstance(child, _Comment)]
-    >>> resources, service_root_type, service_root_repr = children[:3]
+
+    >>> service_doc, version_doc = children[:2]
+    >>> print service_doc.attrib['title']
+    About this service
+    >>> for p_tag in service_doc:
+    ...     print p_tag.text
+    This is a web service.
+    It's got resources!
+
+    >>> print version_doc.attrib['title']
+    About version devel
+    >>> for p_tag in version_doc:
+    ...     print p_tag.text
+    The unstable development version.
+    Don't use this unless you like changing things.
+
+Description of the service root itself
+--------------------------------------
+
+Let's whittle down the complexity a little more by taking a look at
+the description of the service root resource itself.
+
+    >>> resources, service_root_type, service_root_repr = children[2:5]
     >>> # We'll deal with the rest of the children later.
-    >>> other_children = children[3:]
+    >>> other_children = children[5:]
 
 The service root is an instance of a special resource type that
 responds only to GET.
@@ -397,7 +414,6 @@
 Aha! There's a resource of type "service-root" right there at the
 service root! Who would have thought?
 
-========================
 The rest of the document
 ========================
 

=== modified file 'src/lazr/restful/example/multiversion/tests/wadl.txt'
--- src/lazr/restful/example/multiversion/tests/wadl.txt	2010-02-11 16:36:47 +0000
+++ src/lazr/restful/example/multiversion/tests/wadl.txt	2010-03-10 20:48:29 +0000
@@ -24,9 +24,10 @@
     ...         api_version=version).body
     ...     tree = etree.fromstring(wadl)
     ...
-    ...     keys = ("base service_root service_root_json pair_collection "
-    ...             "pair_entry pair_full_json pair_diff_jaon pair_page "
-    ...             "pair_page_json hosted_file hosted_file_representation"
+    ...     keys = ("service_doc version_doc base service_root "
+    ...             "service_root_json pair_collection pair_entry"
+    ...             "pair_full_json pair_diff_jaon pair_page pair_page_json"
+    ...             "hosted_file hosted_file_representation"
     ...             ).split()
     ...
     ...     tags = [child for child in tree if not isinstance(child, _Comment)]
@@ -39,6 +40,9 @@
 is not present at all.
 
     >>> contents = wadl_contents_for_version('beta')
+    >>> print contents['version_doc'].attrib['title']
+    About version beta
+
     >>> print contents['base'].attrib['base']
     http://multiversion.dev/beta/
 
@@ -46,9 +50,20 @@
     >>> sorted([method.attrib['id'] for method in pair_collection])
     ['key_value_pairs-get']
 
+As a side note, see that the service documentation and version
+documentation tags are empty, because this service's configuration
+doesn't specify that information:
+
+    >>> len(list(contents['service_doc']))
+    0
+    >>> len(list(contents['version_doc']))
+    0
+
 In '2.0', the by_value method is called 'byValue'.
 
     >>> contents = wadl_contents_for_version('2.0')
+    >>> print contents['version_doc'].attrib['title']
+    About version 2.0
     >>> print contents['base'].attrib['base']
     http://multiversion.dev/2.0/
 
@@ -59,6 +74,8 @@
 In '3.0', the method changes its name to 'by_value'.
 
     >>> contents = wadl_contents_for_version('3.0')
+    >>> print contents['version_doc'].attrib['title']
+    About version 3.0
     >>> print contents['base'].attrib['base']
     http://multiversion.dev/3.0/
 

=== modified file 'src/lazr/restful/interfaces/_rest.py'
--- src/lazr/restful/interfaces/_rest.py	2010-02-24 18:02:29 +0000
+++ src/lazr/restful/interfaces/_rest.py	2010-03-10 20:48:29 +0000
@@ -52,7 +52,7 @@
     'IWebServiceVersion',
     ]
 
-from zope.schema import Bool, Int, List, TextLine
+from zope.schema import Bool, Dict, Int, List, Text, TextLine
 from zope.interface import Attribute, Interface
 # These two should really be imported from zope.interface, but
 # the import fascist complains because they are not in __all__ there.
@@ -394,6 +394,16 @@
     These are miscellaneous strings that may differ in different web
     services.
     """
+    service_description = TextLine(
+        title=u"Service description",
+        description=u"""A human-readable description of the web service.
+
+        The description may contain HTML, but if it does, it must be a
+        valid XHTML fragment.
+        """,
+        default=u"",
+        )
+
     view_permission = TextLine(
         title=u"View permission", default=u"zope.View",
         description=u"The permission to use when checking object visibility.")
@@ -448,6 +458,21 @@
 
         This list must contain at least one version name.""")
 
+    version_descriptions = Dict(
+        key_type = TextLine(),
+        value_type = Text(),
+        title = u"Human-readable descriptions of the web service versions.",
+        description = u"""A dictionary mapping version names to
+        human-readable descriptions. The descriptions should describe
+        what distinguishes this version from other versions, and
+        mention if/when the version will be removed.
+
+        The descriptions may contain HTML, but if they do, they must be
+        valid XHTML fragments.
+        """,
+        default = {}
+        )
+
     last_version_with_mutator_named_operations = TextLine(
         default=None,
         description=u"""In earlier versions of lazr.restful, mutator methods

=== modified file 'src/lazr/restful/tales.py'
--- src/lazr/restful/tales.py	2010-02-18 15:02:10 +0000
+++ src/lazr/restful/tales.py	2010-03-10 20:48:29 +0000
@@ -32,8 +32,8 @@
     ICollection, ICollectionField, IEntry, IJSONRequestCache,
     IReferenceChoice, IResourceDELETEOperation, IResourceGETOperation,
     IResourceOperation, IResourcePOSTOperation, IScopedCollection,
-    ITopLevelEntryLink, IWebServiceClientRequest, IWebServiceVersion,
-    LAZR_WEBSERVICE_NAME)
+    ITopLevelEntryLink, IWebServiceClientRequest, IWebServiceConfiguration,
+    IWebServiceVersion, LAZR_WEBSERVICE_NAME)
 from lazr.restful.utils import get_current_web_service_request
 
 
@@ -221,6 +221,19 @@
         return self._service_root_url()
 
     @property
+    def description(self):
+        return getUtility(IWebServiceConfiguration).service_description
+
+    @property
+    def service_version(self):
+        return self.resource.request.version
+
+    @property
+    def version_description(self):
+        config = getUtility(IWebServiceConfiguration)
+        return config.version_descriptions.get(self.service_version, None)
+
+    @property
     def top_level_resources(self):
         """Return a list of dicts describing the top-level resources."""
         resource_dicts = []

=== modified file 'src/lazr/restful/templates/wadl-root.pt'
--- src/lazr/restful/templates/wadl-root.pt	2009-10-21 13:41:12 +0000
+++ src/lazr/restful/templates/wadl-root.pt	2010-03-10 20:48:29 +0000
@@ -11,6 +11,19 @@
   xmlns:metal="http://xml.zope.org/namespaces/metal"
 >
 
+  <wadl:doc xmlns="http://www.w3.org/1999/xhtml"
+       title="About this service"
+       tal:content="structure context/wadl:description">
+    Version-independent description of the web service.
+  </wadl:doc>
+
+  <wadl:doc xmlns="http://www.w3.org/1999/xhtml"
+       tal:define="version context/wadl:service_version"
+       tal:attributes="title string:About version ${version}"
+       tal:content="structure context/wadl:version_description">
+    Description of this version of the web service.
+  </wadl:doc>
+
   <!--There is one "service root" resource, located (as you'd expect)
       at the service root. This very document is the WADL
       representation of the "service root" resource.-->