docs: enhance README

Merge pull request #18 from DSD-DBS/enhance-documentation

Author: ewuerger

README.md

@@ -14,13 +14,42 @@ version of the client and a feature complete low level API client, which was gen
 Therefor the OpenAPI Specification of Polarion was used.
 
 ## Usage of the High Level Client
-tbd
-
-## Updating the auto generated part
-To update the auto generated part of the code, execute the `open_api_client_build/build_client_source.sh` script with `path` or `url` as first
-arg and the path to the OpenAPI-Specification as second arg from the project root directory. For Copyright reasons, we don't publish the Specification here,
-but we used the Specification of Polarion version 2023.04 to generate the code published here.
+The high level client is an abstraction of the fine-grained, auto-generated client. It is created for a single project and currently exposes functions for Work Items, their Custom Fields, Links, Attachments and basic support for Documents.
+To get started, create a client and check, if the project exists. In the end, to get all Work Items of a project with an empty query, you can simply run the following code and our client will automatically take care of the paging:
 
+```python
+import polarion_rest_api_client as polarion_api
+
+client = polarion_api.OpenAPIPolarionProjectClient(
+        project_id="PROJ",
+        delete_polarion_work_items=False,
+        polarion_api_endpoint="http://127.0.0.1/api",
+        polarion_access_token="PAT123",
+    )
+project_exists = client.project_exists() # Should be True
+work_items = client.get_all_work_items()
+```
+During the initialization of the client you can define additional settings like the page size when getting items or the maximum content size when bulk creating new items.
+In addition, you can define your own Work Item class with custom fields, which become available as attributes on object level instead of being part of the `additional_attributes` dictionary only.
+To use this feature, inherit from our Work Item class and pass your extended class to the Client on initialization:
+```python
+import polarion_rest_api_client as polarion_api
+
+class CustomWorkItem(polarion_api.WorkItem):
+    capella_uuid: str | None
+
+ client = polarion_api.OpenAPIPolarionProjectClient(
+     project_id="PROJ",
+     delete_polarion_work_items=False,
+     polarion_api_endpoint="http://127.0.0.1/api",
+     polarion_access_token="PAT123",
+     batch_size=3,
+     custom_work_item=CustomWorkItem,
+ )
+
+work_items = client.get_all_work_items() # the returned Work Items will be instances of CustomWorkItem
+uuid = work_items[0].capella_uuid # the value of the custom field capella_uuid can be accessed this way
+```
 ## Usage of the autogenerated OpenAPI Client
 First, create a client:
 
@@ -123,6 +152,11 @@ pip install -e '.[docs,test]'
 pre-commit install
 ```
 
+## Updating the auto generated part
+To update the auto generated part of the code, execute the `open_api_client_build/build_client_source.sh` script with `path` or `url` as first
+arg and the path to the OpenAPI-Specification as second arg from the project root directory. For Copyright reasons, we don't publish the Specification here,
+but we used the Specification of Polarion version 2023.04 to generate the code published here.
+
 # Contributing
 
 We'd love to see your bug reports and improvement suggestions! Please take a

polarion_rest_api_client/base_client.py

@@ -175,7 +175,7 @@ def get_work_item_attachments(
         raise NotImplementedError
 
     def get_all_work_items(
-        self, query: str, fields: dict[str, str] | None = None
+        self, query: str = "", fields: dict[str, str] | None = None
     ) -> list[WorkItemType]:
         """Get all work items matching the given query.
 

polarion_rest_api_client/client.py

@@ -523,7 +523,7 @@ def create_work_item_attachments(
 
     def get_work_items(
         self,
-        query: str,
+        query: str = "",
         fields: dict[str, str] | None = None,
         page_size: int = 100,
         page_number: int = 1,