Merge pull request #1 from hiero-ledger/chore/update-readme

Restructure docs and update README

Author: AlexanderShenshin

CONTRIBUTING.md

@@ -103,7 +103,7 @@ Now, validate that all unit tests are passing:
 make test
 ```
 
-9. Before raising a pull request you should also run tox.
+9. Before raising a pull request it's recommended to also run tox.
    This will run the tests across different versions of Python:
 
 ```bash

README.md

@@ -9,23 +9,24 @@
 The repository contains the Python SDK for managing DID Documents and AnonCreds Verifiable Credentials registry using
 Hedera Consensus Service.
 
-Documentation:
+This library is using [Hiero Python SDK](https://github.com/hiero-ledger/hiero-sdk-python).
 
-- ~~See [SDK docs](https://hiero-ledger.github.io/hiero-did-sdk-python/)~~
-  - Not published yet, see [src in repo](docs/dev)
-- Design documentation can be found in [repo folder](docs/design)
+## Documentation
 
-## Getting started
+### Dev and API
 
-### Prerequisites
+We're planning to publish dev guides along with [mkdocs](https://www.mkdocs.org/)-generated API documentation to GH pages in near future.
+You can find [documentation sources in repo](docs/dev).
 
-- Python 3.12+
-- [Poetry](https://python-poetry.org/) (at least 1.8.4)
-- NodeJS and npm (used by pre-commit hooks)
-- Tools for Makefile support (Windows only)
-  - Can be installed with [chocolatey](https://chocolatey.org/): `choco install make`
+Meanwhile, dev guides have been added to this README for convenience.
+
+If you're planning to contribute to the project, please also check [contribution guidelines](CONTRIBUTING.md).
+
+### Design
 
-### Environment
+SDK design documentation can be found in corresponding [repo folder](docs/design).
+
+## Dev environment
 
 The project uses Makefile for dev scripts. You can view available commands by running:
 
@@ -59,7 +60,184 @@ make test
 make build
 ```
 
-## Releasing a new version
+## Getting started
+
+### Prerequisites
+
+- Python 3.12+
+- [Poetry](https://python-poetry.org/) (at least 1.8.4)
+- NodeJS and npm (used by pre-commit hooks)
+- Tools for Makefile support (Windows only)
+  - Can be installed with [chocolatey](https://chocolatey.org/): `choco install make`
+
+### Install package (from Git source)
+
+```bash
+pip install git+https://github.com/hiero-ledger/hiero-did-sdk-python@main
+```
+
+Please note that PyPi package will soon be published and replace Git source dependency as recommended installation method.
+
+### Example usage
+
+Here you can find basic SDK usage examples.
+
+For more complex examples, please refer to SDK integration tests:
+
+- [Hedera DID](https://github.com/hiero-ledger/hiero-did-sdk-python/blob/main/tests/integration/test_hedera_did.py)
+- [AnonCreds registry](https://github.com/hiero-ledger/hiero-did-sdk-python/blob/main/tests/integration/test_hedera_anoncreds_registry.py)
+
+#### Create Hedera Client (for testnet)
+
+```python
+from hiero_sdk_python import Client, Network, AccountId, PrivateKey
+
+client = Client(
+    network=Network("testnet")
+)
+
+client.set_operator(AccountId.from_string("OPERATOR_ID"), private_key=PrivateKey.from_string("OPERATOR_KEY"))
+```
+
+#### Register new Hedera DID on testnet network and add DID service
+
+```python
+from hiero_did_sdk_python import HederaDid
+
+did = HederaDid(client=client, private_key_der="private_key_der")
+
+await did.register()
+
+await did.add_service(
+    id_=f"{did.identifier}#service-1", service_type="LinkedDomains", service_endpoint="https://example.com/vcs"
+)
+```
+
+#### Resolve existing Hedera DID
+
+```python
+from hiero_did_sdk_python import HederaDidResolver
+
+resolver = HederaDidResolver(client)
+
+resolution_result = await resolver.resolve(
+    "did:hedera:testnet:zvAQyPeUecGck2EsxcsihxhAB6jZurFrBbj2gC7CNkS5o_0.0.5063027")
+```
+
+#### Create AnonCreds credential schema and credential definition
+
+```python
+from hiero_did_sdk_python import HederaAnonCredsRegistry, AnonCredsSchema, AnonCredsCredDef, CredDefValue, CredDefValuePrimary
+
+issuer_did = "did:hedera:testnet:zvAQyPeUecGck2EsxcsihxhAB6jZurFrBbj2gC7CNkS5o_0.0.5063027"
+registry = HederaAnonCredsRegistry(client)
+
+schema = AnonCredsSchema(
+    name="schema-name",
+    issuer_id=issuer_did,
+    attr_names=["name", "age"],
+    version="1"
+)
+
+schema_registration_result = await registry.register_schema(schema, issuer_did, "OPERATOR_KEY_DER")
+
+cred_def = AnonCredsCredDef(
+    schema_id=schema_registration_result.schema_state.schema_id,
+    issuer_id=issuer_did,
+    value=CredDefValue(primary=CredDefValuePrimary(...)),
+    tag="cred-def-tag"
+)
+
+cred_def_registration_result = await registry.register_cred_def(cred_def, issuer_did, "OPERATOR_KEY_DER")
+```
+
+## Configuration
+
+At the moment, SDK comes with following configuration capabilities:
+
+- Hedera Client configuration
+- Cache implementation (optional)
+- Logger configuration (optional)
+
+### Hedera Client configuration
+
+Configuration consists from two parts:
+
+- Network configuration
+  - Basic configuration is lightweight and consists from selection of specific network ("mainnet", "testnet", "
+    previewnet"), complex parts are handled by Hedera Python SDK
+  - Custom configuration can be provided, if necessary
+- Hedera operator (account) configuration
+  - Essentially, account "credentials" that will be used for Hedera network integration and paying fees
+  - Needs to be provided explicitly and can be changed for specific Hedera Client instance via provider class
+
+#### Examples
+
+Create client for Testnet and set operator config:
+
+```python
+from hiero_sdk_python import Client, Network, AccountId, PrivateKey
+
+client = Client(
+    network=Network("testnet")
+)
+
+client.set_operator(AccountId.from_string("OPERATOR_ID"), private_key=PrivateKey.from_string("OPERATOR_KEY"))
+```
+
+Create client provider with custom network config:
+
+```python
+from hiero_sdk_python import Client, Network, AccountId, PrivateKey
+
+TESTNET_NODES = [
+    ("0.testnet.hedera.com:50211", AccountId(0, 0, 3)),
+    ("1.testnet.hedera.com:50211", AccountId(0, 0, 4))
+]
+
+client = Client(
+    network=Network(network="testnet", nodes=TESTNET_NODES, mirror_address="hcs.testnet.mirrornode.hedera.com:5600"),
+)
+client.set_operator(AccountId.from_string("OPERATOR_ID"), private_key=PrivateKey.from_string("OPERATOR_KEY"))
+```
+
+### Cache implementation
+
+SDK utilizes cache to optimize read operations and provides an option to customize cache implementation (individually
+for each resolver instance).
+
+By default, [in-memory cache implementation](https://github.com/hiero-ledger/hiero-did-sdk-python/blob/main/hiero_did_sdk_python/utils/cache.py#L112) is used.
+
+You can create custom cache implementation by inheriting [Cache base class](https://github.com/hiero-ledger/hiero-did-sdk-python/blob/main/hiero_did_sdk_python/utils/cache.py#L25).
+Custom cache instance needs to be provided in resolver constructor arguments.
+
+Classes that accept custom cache implementation:
+
+- [HederaDidResolver](https://github.com/hiero-ledger/hiero-did-sdk-python/blob/main/hiero_did_sdk_python/did/hedera_did_resolver.py)
+- [HederaAnonCredsRegistry](https://github.com/hiero-ledger/hiero-did-sdk-python/blob/main/hiero_did_sdk_python/anoncreds/hedera_anoncreds_registry.py)
+
+#### Example
+
+```python
+from hiero_did_sdk_python import Cache, HederaDidResolver
+
+class CustomCache(Cache):
+  ...
+
+custom_cache_instance = CustomCache[str, object]()
+
+resolver = HederaDidResolver(client, custom_cache_instance)
+```
+
+### Logger configuration
+
+Logger configuration supports following properties that can be set with environment variables:
 
-- Create a [new release](https://github.com/hiero-ledger/hiero-did-sdk-python/releases/new) on GitHub
-- Create a new tag in the form `*.*.*`
+- Log level
+  - Env variable name: `HEDERA_DID_SDK_LOG_LEVEL`
+  - Currently supported values: "DEBUG", "INFO", "WARN", "ERROR"
+- Log format (in string representation)
+  - Env variable name: `HEDERA_DID_SDK_LOG_FORMAT`
+  - For log format pattern reference, please see Python docs:
+    - [Formatter objects](https://docs.python.org/3/library/logging.html#formatter-objects)
+    - [Log record attributes](https://docs.python.org/3/library/logging.html#logrecord-attributes)

docs/dev/configuration.md

@@ -58,7 +58,7 @@ By default, [in-memory cache implementation](modules/common.md#hiero_did_sdk_pyt
 You can create custom cache implementation by inheriting [Cache base class](modules/common.md#hiero_did_sdk_python.utils.cache.Cache).
 Custom cache instance needs to be provided in resolver constructor arguments.
 
-Resolver classes that accept custom cache implementation:
+Classes that accept custom cache implementation:
 
 - [HederaDidResolver](modules/did.md#hiero_did_sdk_python.did.hedera_did_resolver.HederaDidResolver)
 - [HederaAnonCredsRegistry](modules/anoncreds.md#hiero_did_sdk_python.anoncreds.hedera_anoncreds_registry.HederaAnonCredsRegistry)

docs/dev/getting-started.md

@@ -3,13 +3,19 @@
 ## Prerequisites
 
 - Python 3.12+
+- [Poetry](https://python-poetry.org/) (at least 1.8.4)
+- NodeJS and npm (used by pre-commit hooks)
+- Tools for Makefile support (Windows only)
+  - Can be installed with [chocolatey](https://chocolatey.org/): `choco install make`
 
-## Install from PyPi
+## Install package (from Git source)
 
 ```bash
-pip install hiero-did-sdk-python
+pip install git+https://github.com/hiero-ledger/hiero-did-sdk-python@main
 ```
 
+Please note that PyPi package will soon be published and replace Git source dependency as recommended installation method.
+
 ## Example usage
 
 Here you can find basic SDK usage examples.