Merge pull request #17 from marklogic/feature/docs-tweaks

Reorganizing docs and some fixes

Author: rjrudin

README.md

@@ -1 +1,17 @@
-User guide will be here soon. See the CONTRIBUTING.md guide for instructions on developing the client.
+# MarkLogic Python Client
+
+The [Python `requests` library](https://pypi.org/project/requests/) allows Python developers to easily create 
+applications that communicate with the [MarkLogic REST API](https://docs.marklogic.com/guide/rest-dev). The 
+MarkLogic Python Client further simplifies usage of the `requests` library by supporting common authentication 
+strategies with MarkLogic and improving the user experience with some of the more common endpoints in the MarkLogic
+REST API.
+
+An instance of the client can be easily created and then used in the exact same way as the `requests` API:
+
+```
+from marklogic import Client
+client = Client("http://localhost:8000", digest=("python-user", "pyth0n"))
+response = client.get("/v1/search", params={"q": "marklogic and python", "pageLength": 100})
+```
+
+Please see [the user guide](https://marklogic.github.io/marklogic-python-client/) to start using the client.

docs/getting-started.md renamed to docs/creating-client.md

@@ -1,39 +1,26 @@
 ---
 layout: default
-title: Getting Started
-nav_order: 2
+title: Creating a client
+nav_order: 3
+permalink: /client
 ---
 
-**Until the 1.0 release is available**, please follow the instructions in the CONTRIBUTING.md file for installing the 
-MarkLogic Python client into a Python virtual environment.
-
-## Connecting to MarkLogic
-
 The `Client` class is the primary API to interact with in the MarkLogic Python client. The
 `Client` class extends the `requests` 
 [`Session` class](https://docs.python-requests.org/en/latest/user/advanced/#session-objects), thus exposing all methods
 found in both the `Session` class and the `requests` API. You can therefore use a `Client` object in the same manner 
 as you'd use either the `Session` class or the `requests` API.
 
-To try out any of the examples below or in the rest of this guide, you will first need to create a new MarkLogic user. 
-To do so, please go to the Admin application for your MarkLogic instance - e.g. if you are running MarkLogic locally, 
-this will be at <http://localhost:8001>, and you will authenticate as your "admin" user. Then perform the following 
-steps to create a new user:
-
-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. Click on the "rest-reader" and "rest-writer" checkboxes. 
-5. Scroll to the top or bottom and click on "OK" to create the user.
+## Creating a client
 
-A `Client` instance can be constructed either by providing a base URL for all requests along with authentication:
+A `Client` instance can be created either by providing a base URL for all requests along with authentication:
 
 ```
 from marklogic import Client
 client = Client('http://localhost:8000', digest=('python-user', 'pyth0n'))
 ```
 
-Or via separate arguments for each of the parts of a base URL:
+Or via separate arguments for each part of a base URL:
 
 ```
 from marklogic import Client

docs/example-setup.md

@@ -0,0 +1,23 @@
+---
+layout: default
+title: Setup for examples
+nav_order: 2
+permalink: /setup
+---
+
+The examples in this documentation depend on a particular MarkLogic username and password. If you 
+would like to try these examples out against your own installation of MarkLogic, you will need to create this 
+MarkLogic user. To do so, please go to the Admin application for your MarkLogic instance - e.g. if you are running MarkLogic locally, this will be at <http://localhost:8001> - and authenticate as your "admin" user. 
+Then perform the following steps to create a new user:
+
+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. Click on the "rest-reader" and "rest-writer" checkboxes. 
+5. Scroll to the top or bottom and click on "OK" to create the user.
+
+You can verify that you correctly created the user by accessing the REST API for the out-of-the-box REST API 
+server in MarkLogic that listens on port 8000. Go to <http://localhost:8000/v1/search> (changing "localhost" to 
+the correct name of your MarkLogic host if you are not running it locally) in a web browser and enter the 
+username and password for the new user you created. The browser should then display a search response returned by 
+MarkLogic, verifying that the user is able to access the MarkLogic REST API.

docs/index.md

@@ -4,9 +4,28 @@ title: Introduction
 nav_order: 1
 ---
 
-The MarkLogic Python Client further simplifies usage of the 
-[Python `requests` library](https://pypi.org/project/requests/) when developing applications in Python that communicate
-with the [MarkLogic REST API](https://docs.marklogic.com/guide/rest-dev). 
+**Until the 1.0 release is available**, please follow the instructions in the CONTRIBUTING.md file for installing the 
+MarkLogic Python client into a Python virtual environment (this notice will be removed before the release).
 
-See the [Getting Started guide](getting-started.md) to begin using the client.
+The [Python `requests` library](https://pypi.org/project/requests/) allows Python developers to easily create 
+applications that communicate with the [MarkLogic REST API](https://docs.marklogic.com/guide/rest-dev). The 
+MarkLogic Python Client further simplifies usage of the `requests` library by supporting common authentication 
+strategies with MarkLogic and improving the user experience with some of the more common endpoints in the MarkLogic
+REST API.
+
+An instance of the client can be easily created and then used in the exact same way as the `requests` API:
+
+```
+from marklogic import Client
+client = Client("http://localhost:8000", digest=("python-user", "pyth0n"))
+response = client.get("/v1/search", params={"q": "marklogic and python", "pageLength": 100})
+```
+
+The example above and the examples throughout this documentation depend on a MarkLogic user named "python-user". 
+If you wish to try these examples on your own installation of MarkLogic, please see [the setup guide](/setup)
+for instructions on creating this user. 
+
+Otherwise, please see the [guide on creating a client](/client) for more information on connecting to a 
+MarkLogic REST API instance. The [guide on managing documents](/documents) provides
+more information on how the client simplifies writing and reading multiple documents in a single request.
 

docs/managing-documents/managing-documents.md

@@ -1,32 +1,12 @@
 ---
 layout: default
-title: Managing Documents
+title: Managing documents
 nav_order: 3
 has_children: true
-permalink: /docs/managing-documents
+permalink: /documents
 ---
 
-The [/v1/documents endpoint](https://docs.marklogic.com/REST/client/management) in the MarkLogic REST API simplifies
+The [/v1/documents endpoint](https://docs.marklogic.com/REST/client/management) in the MarkLogic REST API supports
 operations that involve writing or reading a single document. It also supports operations that involve multiple 
 documents, though those require use of a potentially complex multipart HTTP request or response. The MarkLogic Python
 client simplifies those operations by hiding the details of multipart requests and responses.
-
-## Setup for examples
-
-The examples shown in [Reading Documents](reading.md) and [Searching Documents](searching.md) assume that you have 
-created a new MarkLogic user named "python-user" as described in the [Getting Started](getting-started.md) guide. 
-The examples also depend on documents being created by the below script. If you would like to run each of the examples, 
-please run the script below, which will create a `Client` instance that interacts with the out-of-the-box "Documents"
-database in MarkLogic.
-
-```
-from marklogic import Client
-from marklogic.documents import Document, DefaultMetadata
-
-client = Client('http://localhost:8000', digest=('python-user', 'pyth0n'))
-client.documents.write([
-    DefaultMetadata(permissions={"rest-reader": ["read", "update"]}, collections=["python-example"]),
-    Document("/doc1.json", {"text": "example one"}),
-    Document("/doc2.json", {"text": "example two"})
-])
-```

docs/managing-documents/reading.md

@@ -1,8 +1,9 @@
 ---
 layout: default
-title: Reading Documents
-parent: Managing Documents
-nav_order: 3
+title: Reading documents
+parent: Managing documents
+nav_order: 2
+permalink: /documents/reading
 ---
 
 The [GET /v1/documents](https://docs.marklogic.com/REST/GET/v1/documents) endpoint in the MarkLogic REST API supports
@@ -12,8 +13,9 @@ handling the response by converting it into a list of `Document` instances via t
 ## Setup for examples
 
 The examples below all assume that you have created a new MarkLogic user named "python-user" as described in the 
-[Getting Started](getting-started.md) guide. To run these examples, please run the following script first, which will 
+[setup guide](/setup). To run these examples, please run the following script first, which will 
 create a `Client` instance that interacts with the out-of-the-box "Documents" database in MarkLogic:
+
 ```
 from marklogic import Client
 from marklogic.documents import Document, DefaultMetadata

docs/managing-documents/searching.md

@@ -1,8 +1,9 @@
 ---
 layout: default
-title: Searching Documents
-parent: Managing Documents
+title: Searching documents
+parent: Managing documents
 nav_order: 3
+permalink: /documents/searching
 ---
 
 The [POST /v1/search endpoint](https://docs.marklogic.com/REST/POST/v1/search) in the MarkLogic REST API supports
@@ -14,8 +15,9 @@ via the `client.documents.search` method.
 ## Setup for examples
 
 The examples below all assume that you have created a new MarkLogic user named "python-user" as described in the 
-[Getting Started](getting-started.md) guide. To run these examples, please run the following script first, which will 
+[setup guide](/setup). To run these examples, please run the following script first, which will 
 create a `Client` instance that interacts with the out-of-the-box "Documents" database in MarkLogic:
+
 ```
 from marklogic import Client
 from marklogic.documents import Document, DefaultMetadata
@@ -122,7 +124,7 @@ docs = client.documents.search(collections=["python-example"])
 assert len(docs) == 2
 ```
 
-Similar to [reading documents](reading.md), you can use the `categories` argument to control what is returned for 
+Similar to [reading documents](/documents/reading), you can use the `categories` argument to control what is returned for 
 each matching document:
 
 ```
@@ -146,7 +148,7 @@ docs = client.documents.search("example", params={"database": "Documents"})
 assert len(docs) == 2
 ```
 
-# Error handling
+## Error handling
 
 A POST call to the /v1/search endpoint in MarkLogic will return an HTTP response with a status code of 200 for a
 successful request. For any other status code, the `client.documents.search` method will the `requests` `Response` object,

docs/managing-documents/writing.md

@@ -1,15 +1,16 @@
 ---
 layout: default
-title: Writing Documents
-nav_order: 2
-parent: Managing Documents
+title: Writing documents
+nav_order: 1
+parent: Managing documents
+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 
-[Getting Started](getting-started.md) guide.
+[setup guide](/setup).
 
 ## Writing documents with metadata
 
@@ -96,7 +97,7 @@ that occurs most recently before it in the list (if one exists).
 ## Additional control over writing a document
 
 The "Usage Notes" section in the [POST /v1/documents documentation](https://docs.marklogic.com/REST/POST/v1/documents)
-describes how several parameters can be used to control how each document is written. Those inputs are:
+describes how several parameters can be used to control how each document is written. Those parameters are:
 
 1. `extension` = a URI suffix for use when [MarkLogic generates the URI](https://docs.marklogic.com/guide/rest-dev/bulk#id_86768).
 2. `directory` = a URI prefix for use when MarkLogic generates the URI.
@@ -113,3 +114,10 @@ URI beginning with "/example/" and ending with ".json", with MarkLogic adding a
 construct the URI:
 
     client.documents.write([Document(null, {"doc": 1}, extension=".json", directory="/example/")])
+
+## Error handling
+
+Because the `client.documents.write` method returns a `requests Response` object, any error that occurs during 
+processing of the request will be captured within that `Response` object. The client does not attempt to provide any 
+additional information, as the MarkLogic REST API will already provide details within the response body and potentially
+the response headers as well.