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

Various small doc improvements

Author: rjrudin

docs/eval.md

@@ -1,13 +1,13 @@
 ---
 layout: default
 title: Executing code
-nav_order: 5
+nav_order: 7
 ---
 
 The [MarkLogic REST service extension](https://docs.marklogic.com/REST/client/service-extension) supports the
 execution of custom code, whether via an inline script or an existing module in your application's modules database. 
-The MarkLogic Python client simplifies execution of custom code both by managing some of the complexity of submitting
-and custom code and also converting the multipart response into more useful Python data types.
+The MarkLogic Python client supports execution of custom code by simplifying the submission of custom code
+and converting the multipart response into more useful Python data types.
 
 ## Setup
 
@@ -26,14 +26,14 @@ The [v1/eval REST endpoint](https://docs.marklogic.com/REST/POST/v1/eval) suppor
 and XQuery queries. Each type of query can be easily submitted via the client:
 
 ```
-client.eval.javascript("fn.currentDateTime()")
-client.eval.xquery("fn:current-dateTime()")
+client.eval(javascript="fn.currentDateTime()")
+client.eval(xquery="fn:current-dateTime()")
 ```
 
 Variables can optionally be provided via a `dict`:
 
 ```
-results = client.eval.javascript('Sequence.from([{"hello": myValue}])', vars={"myValue": "world"})
+results = client.eval(javascript='Sequence.from([{"hello": myValue}])', vars={"myValue": "world"})
 assert "world" == results[0]["hello"]
 ```
 
@@ -48,9 +48,16 @@ and XQuery main modules that have been deployed to your application's modules da
 the client in the following manner:
 
 ```
+# Set the input to the URI of the module you wish to invoke in your application's 
+# modules database.
 client.invoke("/path/to/module.sjs")
 ```
 
+You can provide variables to your module in the same fashion as when evaluating custom code:
+
+```
+client.invoke("/path/to/module.sjs", vars={"my_var1": "value1"})
+```
 
 ## Conversion of data types
 
@@ -59,15 +66,15 @@ value having MarkLogic-specific type information. The client will use this type
 an appropriate Python data type. For example, each JSON object into the example below is converted into a `dict`:
 
 ```
-results = client.eval.javascript('Sequence.from([{"doc": 1}, {"doc": 2}])')
+results = client.eval(javascript='Sequence.from([{"doc": 1}, {"doc": 2}])')
 assert len(results) == 2
 assert results[0]["doc"] == 1
 assert results[1]["doc"] == 2
 ```
 
 The following table describes how each MarkLogic type is associated with a Python data type. For any 
-MarkLogic type not listed in the table, such as `hexBinary` and `base64Binary`, the value is not converted and will be 
-of type `bytes`. 
+MarkLogic type not listed in the table, such as `hexBinary` and `base64Binary`, the value is not converted and will 
+remain of type `bytes`. 
 
 | MarkLogic type | Python type | 
 | --- | --- |
@@ -92,3 +99,9 @@ the multipart `X-URI` header. Otherwise, a value of type `dict`, `str`, or `byte
 Each `client.eval` method and `client.invoke` accept a `return_response` argument. When that
 argument is set to `True`, the original response is returned. This can be useful for custom
 processing of the response or debugging requests.
+
+## Referencing a transaction
+
+The `client.eval` and `client.invoke` functions both support referencing a 
+[REST API transaction](https://docs.marklogic.com/REST/client/transaction-management) via the `tx` 
+argument. See [the guide on transactions](transactions.md) for further information.

docs/example-setup.md

@@ -13,17 +13,17 @@ Then perform the following steps to create a new role:
 
 1. Click on "Roles" in the "Security" box. 
 2. Click on "Create".
-3. In the form, enter "python-docs-role" for "Role Name".
-4. Scroll down and select the "rest-extension-user", "rest-reader", "rest-writer", and "tde-admin" roles.
-5. Scroll further down and select the "xdbc:eval", "xdbc:invoke", and "xdmp:eval-in" privileges.
+3. In the form, enter `python-docs-role` for "Role Name".
+4. Scroll down and select the `rest-extension-user`, `rest-reader`, `rest-writer`, and `tde-admin` roles.
+5. Scroll further down and select the `xdbc:eval`, `xdbc:invoke`, and `xdmp:eval-in` privileges.
 6. Scroll to the top or bottom and click on "OK" to create the role.
 
 After creating the role, return to the Admin application home page and perform the following steps:
 
 1. Click on "Users" in the "Security" box.
 2. Click on "Create".
-3. In the form, enter "python-user" for "User Name" and "pyth0n" as the password. 
-4. Scroll down until you see the "Roles" section and select the "python-docs-role" role. 
+3. In the form, enter `python-user` for "User Name" and `pyth0n` as the password. 
+4. Scroll down until you see the "Roles" section and select the `python-docs-role` role. 
 5. Scroll to the top or bottom and click on "OK" to create the user.
 
 (Note that you could use the `admin` role instead to grant full access to all features in MarkLogic, but this is 

docs/index.md

@@ -31,6 +31,6 @@ If you wish to try these examples on your own installation of MarkLogic, please
 for instructions on creating this user. 
 
 Otherwise, please see the [guide on creating a client](creating-client.md) for more information on connecting to a 
-MarkLogic REST API instance. The [guide on managing documents](managing-documents/managing-documents.md) provides
-more information on how the client simplifies writing and reading multiple documents in a single request.
+MarkLogic REST API instance. Then choose a guide from the navigation on the left to see how the client can simplify
+your application's interactions with the MarkLogic REST API.
 

docs/managing-documents/managing-documents.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Managing documents
-nav_order: 3
+nav_order: 4
 has_children: true
 permalink: /documents
 ---

docs/managing-documents/reading.md

@@ -116,9 +116,15 @@ for more information on reading documents.
 
 ## Returning the original HTTP response
 
-The `client.documents.read` method also accepts a `return_response` argument. When that
-argument is set to `True`, the original response is returned. This can be useful for custom
-processing of the response or debugging requests.
+Starting in the 1.1.0 release, the `client.documents.search` method accepts a 
+`return_response` argument. When that argument is set to `True`, the original response 
+is returned. This can be useful for custom processing of the response or debugging requests.
+
+## Referencing a transaction
+
+Starting in the 1.1.0 release, you can reference a 
+[REST API transaction](https://docs.marklogic.com/REST/client/transaction-management) via the `tx` 
+argument. See [the guide on transactions](../transactions.md) for further information.
 
 ## Error handling
 

docs/managing-documents/searching.md

@@ -157,9 +157,15 @@ for more information on searching documents.
 
 ## Returning the original HTTP response
 
-The `client.documents.search` method also accepts a `return_response` argument. When
-that argument is set to `True`, the original response is returned. This can be useful for
-custom processing of the response or debugging requests.
+Starting in the 1.1.0 release, the `client.documents.search` method accepts a 
+`return_response` argument. When that argument is set to `True`, the original response 
+is returned. This can be useful for custom processing of the response or debugging requests.
+
+## Referencing a transaction
+
+Starting in the 1.1.0 release, you can reference a 
+[REST API transaction](https://docs.marklogic.com/REST/client/transaction-management) via the `tx` 
+argument. See [the guide on transactions](../transactions.md) for further information.
 
 ## Error handling
 

docs/managing-documents/writing.md

@@ -150,6 +150,13 @@ response = client.documents.write(Document("/doc1.json", {"doc": 1}, permissions
 Please see [the application developer's guide](https://docs.marklogic.com/guide/rest-dev/documents#id_11953) for 
 more information on writing documents.
 
+## Referencing a transaction
+
+Starting in the 1.1.0 release, you can reference a 
+[REST API transaction](https://docs.marklogic.com/REST/client/transaction-management) via the `tx` 
+argument. See [the guide on transactions](../transactions.md) for further information.
+
+
 ## Error handling
 
 Because the `client.documents.write` method returns a `requests Response` object, any error that occurs during 

docs/rows.md

@@ -1,13 +1,13 @@
 ---
 layout: default
 title: Querying for rows
-nav_order: 4
+nav_order: 6
 ---
 
 
 The [MarkLogic REST rows service](https://docs.marklogic.com/REST/client/row-management) supports
-operations for querying for rows via a variety of languages. The MarkLogic Python client simplifies submitting queries
-for rows and converting the response into a useful data structure.
+operations for querying for rows via several query languages. The MarkLogic Python client simplifies submitting queries
+for rows and converting responses into useful data structures.
 
 ## Setup
 
@@ -85,16 +85,17 @@ You can use a named argument as well:
 client.rows.query(dsl="op.fromView('example', 'musician')")
 ```
 
-For some use cases, it may be helpful to capture an Optic query in its serialized form. Such a query can then be 
-submitted via the `plan` argument:
+For some use cases, it may be helpful to capture an Optic query 
+[as a serialized plan](https://docs.marklogic.com/guide/app-dev/OpticAPI#id_11208). 
+A serialized plan can then be submitted via the `plan` argument:
 
 ```
 plan = '{"$optic":{"ns":"op", "fn":"operators", "args":[{"ns":"op", "fn":"from-view", "args":["example", "musician"]}]}}'
 client.rows.query(plan=plan)
 ```
 
 Optic supports many different types of queries and operations; please
-[see the documentation]((https://docs.marklogic.com/guide/app-dev/OpticAPI#id_35559)) for further information on 
+[see the documentation](https://docs.marklogic.com/guide/app-dev/OpticAPI#id_35559) for further information on 
 much more powerful and flexible queries than shown in these examples, which are intended solely for demonstration of 
 how to submit an Optic query.
 

docs/transactions.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Managing transactions
-nav_order: 6
+nav_order: 5
 ---
 
 The [MarkLogic REST transactions service](https://docs.marklogic.com/REST/client/transaction-management)
@@ -76,7 +76,9 @@ with client.transactions.create() as tx:
 
 ## Getting transaction status
 
-You can get the status of the transaction via the `get_status()` function:
+You can get the 
+[status of the transaction](https://docs.marklogic.com/REST/GET/v1/transactions/[txid]) 
+via the `get_status()` function:
 
 ```
 with client.transactions.create() as tx: