Merge pull request #24 from marklogic/feature/docs-tweak

Added list of values for categories in docs for searching

Author: rjrudin

docs/managing-documents/reading.md

@@ -35,8 +35,19 @@ A list of `Document` instances can be obtained for a list of URIs, where each `D
 attributes populated but no metadata by default:
 
 ```
+# Read multiple documents via a list of URIs.
 docs = client.documents.read(["/doc1.json", "/doc2.xml", "/doc3.bin"])
 assert len(docs) == 3
+
+# Read a single document, verifying that it does not have any metadata.
+doc = client.documents.read("/doc1.json")[0]
+assert "/doc1.json" == doc.uri
+assert "example one" == doc.content["text"]
+assert doc.collections is None
+assert doc.permissions is None
+assert doc.quality is None
+assert doc.metadata_values is None
+assert doc.properties is None
 ```
 
 The [requests toolbelt](https://toolbelt.readthedocs.io/en/latest/) library is used to process the multipart
@@ -100,6 +111,9 @@ docs = client.documents.read(uris, params={"database": "Documents"})
 print(docs)
 ```
 
+Please see [the application developer's guide](https://docs.marklogic.com/guide/rest-dev/documents#id_80116)
+for more information on reading documents.
+
 ## Error handling
 
 If the `client.documents.read` method receives an HTTP response with a status code of 200, then the client will return

docs/managing-documents/searching.md

@@ -124,8 +124,11 @@ docs = client.documents.search(collections=["python-search-example"])
 assert len(docs) == 2
 ```
 
-Similar to [reading documents](reading.md), you can use the `categories` argument to control what is returned for 
-each matching document:
+Metadata for each document can be retrieved via the `categories` argument. The acceptable values for this argument
+match those of the `category` parameter in the [search endpoint](https://docs.marklogic.com/REST/POST/v1/search)
+documentation: `content`, `metadata`, `metadata-values`, `collections`, `permissions`, `properties`, and `quality`.
+
+The following shows different examples of configuring the `categories` argument:
 
 ```
 # Retrieve all content and metadata for each matching document.
@@ -149,6 +152,9 @@ docs = client.documents.search("hello", params={"database": "Documents"})
 assert len(docs) == 2
 ```
 
+Please see [the application developer's guide](https://docs.marklogic.com/guide/rest-dev/search#id_49329)
+for more information on searching documents.
+
 ## Error handling
 
 If the `client.documents.read` method receives an HTTP response with a status code of 200, then the client will return

docs/managing-documents/writing.md

@@ -147,6 +147,9 @@ normally pass to `requests`. For example:
 response = client.documents.write(Document("/doc1.json", {"doc": 1}, permissions=default_perms), params={"database": "Documents"})
 ```
 
+Please see [the application developer's guide](https://docs.marklogic.com/guide/rest-dev/documents#id_11953) for 
+more information on writing documents.
+
 ## Error handling
 
 Because the `client.documents.write` method returns a `requests Response` object, any error that occurs during