Merge pull request #18 from marklogic/feature/doc-fixes

Fixes for the docs on writing

Author: rjrudin

docs/managing-documents/writing.md

@@ -9,66 +9,85 @@ permalink: /documents/writing
 The [POST /v1/documents](https://docs.marklogic.com/REST/POST/v1/documents) endpoint in the MarkLogic REST API supports
 writing multiple documents with metadata via a multipart HTTP request. The MarkLogic Python client 
 simplifies the use of this endpoint via the `client.documents.write` method and the `Document`
-class. The examples below all assume that you have constructed a `Client` instance already as described in the 
-[setup guide](/setup).
+class. 
+
+The examples below all assume that you have created a new MarkLogic user named "python-user" as described in the 
+[setup guide](/setup). In addition, each of the examples below requires the following `Client` instance to be created 
+first:
+
+```
+from marklogic import Client
+client = Client('http://localhost:8000', digest=('python-user', 'pyth0n'))
+```
 
 ## Writing documents with metadata
 
 Writing a document requires specifying a URI, the document content, and at least one update permission (a user with the
 "admin" role does not need to specify an update permission, but using such a user in an application is not encouraged).
 The example below demonstrates this; the `default_perms` variable is used in subsequent examples. 
 
-    from marklogic.documents import Document
-    default_perms = {"rest-reader": ["read", "update"]}
-    response = client.documents.write(Document("/doc1.json", {"doc": 1}, permissions=default_perms))
+```
+from marklogic.documents import Document
+default_perms = {"rest-reader": ["read", "update"]}
+response = client.documents.write(Document("/doc1.json", {"doc": 1}, permissions=default_perms))
+```
 
 The `write` method returns a [Response instance](https://requests.readthedocs.io/en/latest/api/#requests.Response) 
 from the `requests` API, giving you access to everything returned by the MarkLogic REST API.
 
 The `Document` class supports all of the types of metadata that can be assigned to a document:
 
-    doc = Document(
-        "/doc1.json", 
-        {"doc": 1},
-        permissions=default_perms,
-        collections=["c1", "c2"],
-        quality=10,
-        metadata_values={"key1": "value1", "key2": "value2"},
-        properties={"prop1": "value1", "prop2": 2}
-    )
-    client.documents.write(doc)
+```
+doc = Document(
+    "/doc1.json", 
+    {"doc": 1},
+    permissions=default_perms,
+    collections=["c1", "c2"],
+    quality=10,
+    metadata_values={"key1": "value1", "key2": "value2"},
+    properties={"prop1": "value1", "prop2": 2}
+)
+client.documents.write(doc)
+```
 
 Multiple documents can be written in a single call, each with their own metadata:
 
-    client.documents.write([
-        Document("/doc1.json", {"doc": 1}, permissions=default_perms, collections=["example"])
-        Document("/doc2.json", {"doc": 2}, permissions=default_perms, quality=5),
-    ])
+```
+client.documents.write([
+    Document("/doc1.json", {"doc": 1}, permissions=default_perms, collections=["example"]),
+    Document("/doc2.json", {"doc": 2}, permissions=default_perms, quality=5),
+])
+```
 
 ## Writing documents with different content types
 
 The examples above create documents with a dictionary as content, resulting in JSON documents in MarkLogic. An XML 
 document can be created with content defined via a string, including in the same request that creates a JSON document:
 
-    client.documents.write([
-        Document("/doc1.json", {"doc": 1}, permissions=default_perms)
-        Document("/doc2.xml", "<doc>2</doc>", permissions=default_perms),
-    ])
+```
+client.documents.write([
+    Document("/doc1.json", {"doc": 1}, permissions=default_perms),
+    Document("/doc2.xml", "<doc>2</doc>", permissions=default_perms),
+])
+```
 
 Binary documents can be created by passing in binary content:
 
-    client.documents.write([Document("/doc1.bin", b"example content", permissions=default_perms)])
+```
+client.documents.write([Document("/doc1.bin", b"example content", permissions=default_perms)])
+```
 
 A `Document` has a `content_type` attribute that allows for explicitly defining the 
 mimetype of a document. This feature is useful in a scenario where MarkLogic does not 
 have a mimetype registered for the URI extension, or there is no extension:
 
-    client.documents.write([Document(
-        "/doc1", "some text", 
-        permissions=default_perms, 
-        content_type="text/plain
-    )])
-
+```
+client.documents.write([Document(
+    "/doc1", "some text", 
+    permissions=default_perms, 
+    content_type="text/plain"
+)])
+```
 
 ## Specifying default metadata
 
@@ -79,12 +98,14 @@ instance, unless it specifies its own metadata.
 
 Consider the following example:
 
-    from marklogic.documents import Document, DefaultMetadata
-    client.documents.write([
-        DefaultMetadata(perms=default_perms, collections=["example"]),
-        Document("/doc1.json", {"doc": 1}),
-        Document("/doc2.json", {"doc": 2", perms=default_perms, quality=10})
-    ])
+```
+from marklogic.documents import Document, DefaultMetadata
+client.documents.write([
+    DefaultMetadata(permissions=default_perms, collections=["example"]),
+    Document("/doc1.json", {"doc": 1}),
+    Document("/doc2.json", {"doc": 2}, permissions=default_perms, quality=10)
+])
+```
 
 The first document will be written with the metadata specified in the first `DefaultMetadata` instance. The second
 document will not use the default metadata since it specifies its own metadata. It will have the same permissions, but 
@@ -113,7 +134,9 @@ The following shows an example of writing a document without specifying a URI, w
 URI beginning with "/example/" and ending with ".json", with MarkLogic adding a random identifier in between to 
 construct the URI:
 
-    client.documents.write([Document(null, {"doc": 1}, extension=".json", directory="/example/")])
+```
+client.documents.write([Document(None, {"doc": 1}, extension=".json", directory="/example/")])
+```
 
 ## Error handling