Improve documentation by adding better auto-generated examples.

docs/source/_json/collection.json

@@ -6,7 +6,7 @@
   "creators": [
     "test_user_1_"
   ], 
-  "description": "A collection", 
+  "description": "This is a collection with two documents", 
   "effective": "1969-12-31T00:00:00+01:00", 
   "exclude_from_nav": "False", 
   "expires": "2499-12-31T00:00:00+01:00", 
@@ -17,7 +17,14 @@
   "limit": "1000", 
   "meta_type": "Dexterity Item", 
   "portal_type": "Collection", 
+  "query": [
+    {
+      "i": "Type", 
+      "o": "plone.app.querystring.operation.string.is", 
+      "v": "Document"
+    }
+  ], 
   "relatedItems": [], 
   "rights": "", 
-  "title": "Collection"
+  "title": "My Collection"
 }

docs/source/_json/file.json

@@ -2,8 +2,8 @@
   "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/file", 
   "@type": "Resource", 
-  "description": "A file", 
+  "description": "This is a file", 
   "download": "http://localhost:55001/plone/file/@@download", 
   "portal_type": "File", 
-  "title": "File"
+  "title": "My File"
 }

docs/source/_json/folder.json

@@ -6,20 +6,31 @@
   "creators": [
     "test_user_1_"
   ], 
-  "description": "A folder", 
+  "description": "This is a folder with two documents", 
   "effective": "1969-12-31T00:00:00+01:00", 
   "exclude_from_nav": "False", 
   "expires": "2499-12-31T00:00:00+01:00", 
   "icon": "++resource++plone.dexterity.item.gif", 
   "isAnObjectManager": "1", 
   "isPrincipiaFolderish": "1", 
   "language": "", 
-  "member": [], 
+  "member": [
+    {
+      "@id": "http://localhost:55001/plone/folder/doc1/@@json", 
+      "description": "", 
+      "title": "A document within a folder"
+    }, 
+    {
+      "@id": "http://localhost:55001/plone/folder/doc2/@@json", 
+      "description": "", 
+      "title": "A document within a folder"
+    }
+  ], 
   "meta_type": "Dexterity Container", 
   "meta_types": [], 
   "nextPreviousEnabled": "False", 
   "portal_type": "Folder", 
   "relatedItems": [], 
   "rights": "", 
-  "title": "Folder"
+  "title": "My Folder"
 }

docs/source/_json/image.json

@@ -2,10 +2,10 @@
   "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
   "@id": "http://localhost:55001/plone/image", 
   "@type": "Resource", 
-  "description": "An image", 
+  "description": "This is an image", 
   "download": "http://localhost:55001/plone/image/@@download", 
   "portal_type": "Image", 
-  "title": "Image", 
+  "title": "My Image", 
   "versions": [
     "http://localhost:55001/plone/image/@@images/image/large", 
     "http://localhost:55001/plone/image/@@images/image/preview", 

docs/source/_json/link.json

@@ -6,7 +6,7 @@
   "creators": [
     "test_user_1_"
   ], 
-  "description": "A link", 
+  "description": "This is a link", 
   "effective": "1969-12-31T00:00:00+01:00", 
   "exclude_from_nav": "False", 
   "expires": "2499-12-31T00:00:00+01:00", 
@@ -17,5 +17,5 @@
   "portal_type": "Link", 
   "remoteUrl": "http://", 
   "rights": "", 
-  "title": "Link"
+  "title": "My Link"
 }

docs/source/_json/newsitem.json

@@ -6,7 +6,7 @@
   "creators": [
     "test_user_1_"
   ], 
-  "description": "A news item", 
+  "description": "This is a news item", 
   "effective": "1969-12-31T00:00:00+01:00", 
   "exclude_from_nav": "False", 
   "expires": "2499-12-31T00:00:00+01:00", 
@@ -18,5 +18,5 @@
   "relatedItems": [], 
   "rights": "", 
   "text": "<p>Lorem ipsum</p>", 
-  "title": "News"
+  "title": "My News Item"
 }

src/plone/restapi/tests/test_documentation.py

@@ -67,8 +67,8 @@ def test_documentation_document(self):
 
     def test_documentation_news_item(self):
         self.portal.invokeFactory('News Item', id='newsitem')
-        self.portal.newsitem.title = 'News'
-        self.portal.newsitem.description = u'A news item'
+        self.portal.newsitem.title = 'My News Item'
+        self.portal.newsitem.description = u'This is a news item'
         self.portal.newsitem.text = RichTextValue(
             u"Lorem ipsum",
             'text/plain',
@@ -85,8 +85,8 @@ def test_documentation_news_item(self):
 
     def test_documentation_link(self):
         self.portal.invokeFactory('Link', id='link')
-        self.portal.link.title = 'Link'
-        self.portal.link.description = u'A link'
+        self.portal.link.title = 'My Link'
+        self.portal.link.description = u'This is a link'
         self.portal.remoteUrl = 'http://plone.org'
         import transaction
         transaction.commit()
@@ -99,8 +99,8 @@ def test_documentation_link(self):
 
     def test_documentation_file(self):
         self.portal.invokeFactory('File', id='file')
-        self.portal.file.title = 'File'
-        self.portal.file.description = u'A file'
+        self.portal.file.title = 'My File'
+        self.portal.file.description = u'This is a file'
         pdf_file = os.path.join(
             os.path.dirname(__file__), u'file.pdf'
         )
@@ -125,8 +125,8 @@ def test_documentation_file(self):
 
     def test_documentation_image(self):
         self.portal.invokeFactory('Image', id='image')
-        self.portal.image.title = 'Image'
-        self.portal.image.description = u'An image'
+        self.portal.image.title = 'My Image'
+        self.portal.image.description = u'This is an image'
         image_file = os.path.join(os.path.dirname(__file__), u'image.png')
         self.portal.image.image = NamedBlobImage(
             data=open(image_file, 'r').read(),
@@ -146,8 +146,18 @@ def test_documentation_image(self):
 
     def test_documentation_folder(self):
         self.portal.invokeFactory('Folder', id='folder')
-        self.portal.folder.title = 'Folder'
-        self.portal.folder.description = u'A folder'
+        self.portal.folder.title = 'My Folder'
+        self.portal.folder.description = u'This is a folder with two documents'
+        self.portal.folder.invokeFactory(
+            'Document',
+            id='doc1',
+            title='A document within a folder'
+        )
+        self.portal.folder.invokeFactory(
+            'Document',
+            id='doc2',
+            title='A document within a folder'
+        )
         import transaction
         transaction.commit()
         response = requests.get(
@@ -159,8 +169,24 @@ def test_documentation_folder(self):
 
     def test_documentation_collection(self):
         self.portal.invokeFactory('Collection', id='collection')
-        self.portal.collection.title = 'Collection'
-        self.portal.collection.description = u'A collection'
+        self.portal.collection.title = 'My Collection'
+        self.portal.collection.description = \
+            u'This is a collection with two documents'
+        self.portal.collection.query = [{
+            'i': 'Type',
+            'o': 'plone.app.querystring.operation.string.is',
+            'v': 'Document',
+        }]
+        self.portal.invokeFactory(
+            'Document',
+            id='doc1',
+            title='Document 1'
+        )
+        self.portal.invokeFactory(
+            'Document',
+            id='doc2',
+            title='Document 2'
+        )
         import transaction
         transaction.commit()
         response = requests.get(