Consolidates documentation into a single page (#62)

docs/index.md

@@ -1,3 +1,8 @@
+---
+hide:
+  - navigation
+---
+
 # Introduction
 
 Keystone provides a light-weight Python client for streamlining interactions with the application's REST API.
@@ -11,26 +16,123 @@ The Python client is hosted on PyPI and can be installed in the standard fashion
 pip install keystone-api-client
 ```
 
-## Getting Started
+## Instantiating a Client
+
+The `KeystoneClient` class is used to encapsulate user authentication and API requests.
+New instances are created by specifying the API URL.
+In the following example, a client instance is defined for a locally running server on port `8000`.
+
+```python
+from keystone_client import KeystoneClient
+
+client = KeystoneClient(url="http://localhost:8000") # (1)!
+```
+
+1. Specifying a network protocol is required when instantiating new instances (e.g., `http://` or `https://`).
+
+The `login` and `logout` methods are used to handle user authentication.
+Once authenticated, the client will automatically manage the resulting user credentials.
+
+```python
+client.login(username="username", password="password") # (1)!
+assert client.is_authenticated # (2)!
+client.logout() # (3)!
+```
+
+1. Authenticate a new user session.
+2. Check the authentication status at any time.
+3. End the authenticated session and invalidate current credentials.
+
+## Generic HTTP Requests
+
+The client class provides dedicated methods for each HTTP request type supported by the API.
+When authenticated, the client will automatically include the appropriate authentication headers when submitting
+requests.
+
+| HTTP Method | Function Name | Description                                              |
+|-------------|---------------|----------------------------------------------------------|
+| `GET`       | `http_get`    | Retrieve data from the server at the specified resource. |
+| `POST`      | `http_post`   | Submit a new record to be processed by the server.       |
+| `PUT`       | `http_put`    | Replace an existing record with a new one.               |
+| `PATCH`     | `http_patch`  | Partially update an existing record.                     |
+| `DELETE`    | `http_delete` | Remove the specified record from the server.             |
+
+Request/response logic is handled using the popular `requests` library.
+API responses are returned as `requests.Response` objects encapsulating the response data and status code.
+
+```python
+response = client.http_get('version')
+
+print(response.status_code)
+print(response.content)
+```
+
+## CRUD Operations
+
+Dedicated methods are provided for create, retrieve, update, and delete (CRUD) operations for each API resource.
+These methods simplify data manipulation by automatically handling the request and response logic.
+
+CRUD methods adhere to the following naming scheme:
+
+| Method Name           | Description                                              |
+|-----------------------|----------------------------------------------------------|
+| `create_{resource}`   | Create a new record for the specified resource.          |
+| `retrieve_{resource}` | Retrieve one or more records for the specified resource. |
+| `update_{resource}`   | Update an existing record for the specified resource.    |
+| `delete_{resource}`   | Delete an existing record for the specified resource.    |
+
+### Creating Records
+
+Create methods are used to submit new records to the API server.
+These methods accept record details as keyword arguments and return a dictionary with the successfully created record data.
+
+```python
+new_record_data = client.create_cluster(
+    name="New-Cluster",
+    description="Cluster created for example purposes."
+)
+```
+
+### Retrieving Records
 
-For more information, see the resources below.
+Data retrieval methods are used to search and return existing records.
+By default, these methods return all available records on the server as a list of dictionaries.
+The `filters` argument can be used to optionally filter these values against a set of search parameters.
+See the [filtering requests documentation](../../keystone-api/api/filtering/) for instructions on structuring search queries.
+
+```python
+all_cluster_data = client.retrieve_cluster(filters={"name": "New-Cluster"})
+```
 
-<div class="grid cards" markdown>
+In situations where a record's primary key (i.e., it's `id` field) is already known, the individual record can be retrieved directly. 
 
--   :material-rocket-launch: **User Guide**
+```python
+cluster_pk_one = client.retrieve_cluster(pk=1)
+```
 
-    ---
+### Updating Records
 
-    Get up and running with the client quickstart guide.
+Update operations are used to modify values for an existing record.
+Doing so requires specifying the record's primary key in addition to the new record values.
 
-    [:octicons-arrow-right-24: Get Started](user_guide.md)
+```python
+updated_record_data = client.update_cluster(
+    pk=1,
+    data={'description': "Updated description"}
+)
+```
 
--   :octicons-codescan-16: **Source Code Reference**
+### Deleting Records
 
-    ---
+Delete methods are used to removed records from the server.
 
-    Low level developer documentation for the Keystone-API Python client.
+```python
+client.delete_cluster(pk=1)
+```
 
-    [:octicons-arrow-right-24: See the Docs](client_reference.md)
+If a record does not exist for the provided primary key, the function call will exit silently.
+The `raise_not_exists` argument can be used to raise an exception instead.
 
-</div>
+```python
+client.delete_cluster(pk=1, raise_not_exists=True)
+```

mkdocs.yml

@@ -1,5 +1 @@
 site_name: Keystone Python Client
-nav:
-  - index.md
-  - user_guide.md
-  - Client Reference: client_reference.md