Initial documentation using MkDocs (#123)

* mkdocs setup and first few pages

* revert makefile dev python to 3.9; minor docs edit

* bump black version to 22.3

* delete extra files

* add deploy contract docs page

.gitignore

@@ -6,6 +6,9 @@ dist/
 build/
 Pipfile.lock
 
+# mkdocs documentation
+/site
+
 # IDEs
 .idea/
 

MANIFEST.in

@@ -4,6 +4,7 @@ include Pipfile
 include strategy.ini
 include tox.ini
 include *.md
+include mkdocs.yml
 recursive-include contracts *.wasm
 recursive-include docs *.*
 recursive-include examples *.py

Makefile

@@ -161,19 +161,9 @@ copyright-check:
 ### Docs generation
 ####################
 
-.PHONY: generate-docs
-generate-docs:
-	sphinx-apidoc -f -o $(PYCOSM_DOCS_DIR)/source $(PYCOSM_SRC_DIR) $(PYCOSM_SRC_DIR)/vulture_whitelist.py
-	cd $(PYCOSM_DOCS_DIR) && $(MAKE) html
-
-# Open docs main page in default browser
-.PHONY: open-docs
-open-docs:
-ifneq ($(wildcard $(PYCOSM_DOCS_DIR)/build),)
-	$(OPEN_CMD) $(PYCOSM_DOCS_DIR)/build/html/index.html
-else
-	@echo "Built docs are not found. Please run '$(MAKE) generate-docs' first."
-endif
+.PHONY: docs
+docs:
+	mkdocs build --clean
 
 ####################
 ### Clean and init commands
@@ -193,7 +183,7 @@ clean-build:
 
 .PHONY: clean-docs
 clean-docs:
-	rm -fr docs/build/
+	rm -fr site/
 
 .PHONY: clean-pyc
 clean-pyc:

docs/connect-to-network.md

@@ -0,0 +1,23 @@
+# Connect to a network
+
+To start interacting with a blockchain, you first need to establish a connection to a network node. You can use `LedgerClient` as a client object which takes a `NetworkConfig` as an argument.
+
+```python
+from cosmpy.aerial.client import LedgerClient, NetworkConfig
+
+ledger_client = LedgerClient(NetworkConfig.fetch_mainnet())
+```
+
+For convenience, some networks' configurations are provided automatically. For example, `NetworkConfig.fetch_mainnet()` is the configuration for the Fetch ledger. If you want to target other chains, you can customise `NetworkConfig` as shown in the example below:
+
+```python
+cfg = NetworkConfig(
+    chain_id="cosmoshub-4",
+    url="grpc+https://...",
+    fee_minimum_gas_price=1,
+    fee_denomination="uatom",
+    staking_denomination="uatom",
+)
+
+ledger = LedgerClient(cfg)
+```

docs/css/my-styles.css

@@ -0,0 +1,37 @@
+pre {
+    background-color: #f8f8f7;
+}
+
+code {
+    background-color: #0083fb;
+}
+
+/* this doesn't work now
+.md-nav__link {
+  text-transform: uppercase;
+  color: #0083fb;
+}
+*/
+
+/* Katharine's css additions */
+.md-header,
+.md-tabs,
+.md-footer-meta,
+.md-footer-nav,
+.md-footer-nav__inner {
+    background-color: #172b6e;
+}
+
+.md-nav__title {
+    color: #172b6e;
+}
+
+.md-icon {
+    ./assets/images/favicon.ico;
+}
+
+/* Needed so that Mermaid UML diagrams don't end up being massively tall */
+svg{
+    height: auto;
+
+}

docs/deploy-a-contract.md

@@ -0,0 +1,47 @@
+# Contract Deployment
+
+You can deploy smart contracts in CosmPy using `LedgerContract`. For this, you will need the path to where the contract is stored (in this case `simple.wasm`), a [`LedgerClient`](connect-to-network.md) and a [`Wallet`](wallets-and-keys.md):
+
+```python
+from cosmpy.aerial.contract import LedgerContract
+
+PATH = "../simple.wasm"
+
+contract = LedgerContract(PATH, ledger_client)
+contract.deploy({}, wallet)
+```
+
+You can now start interacting with the contract. To get the address of where the contract is deployed on the network:
+
+```python
+print(f"Contract deployed at: {contract.address}")
+```
+
+You can query the values of the contract's state variables: 
+
+```python
+result = contract.query({"get": {"owner": str(wallet.address())}})
+print("Initial state:", result)
+```
+
+You can also set these values. The following sets the state variable `value` to `foobar`:
+
+```python
+contract.execute({"set": {"value": "foobar"}}, wallet).wait_to_complete()
+```
+
+Let's check if this was set correctly:
+
+```python
+result = contract.query({"get": {"owner": str(wallet.address())}})
+print("State after set:", result)
+```
+
+Similarly, you can clear the state variables:
+
+```python
+contract.execute({"clear": {}}, wallet).wait_to_complete()
+
+result = contract.query({"get": {"owner": str(wallet.address())}})
+print("State after clear:", result)
+```

docs/index.md

@@ -0,0 +1,52 @@
+Cosmpy is a Python library for interacting with Cosmos-based blockchains.
+
+* A simplified Cosmos-SDK agnostic API for basic chain operations.
+* An easy API for deploying and interacting with CosmWasm-based smart contracts.
+* Low-level access to primitive ledger APIs if required.
+
+## To install
+
+``` bash
+pip3 install cosmpy
+```
+
+## Version
+
+<a href="https://img.shields.io/pypi/v/cosmpy" target="_blank"><img alt="PyPI" src="https://img.shields.io/pypi/v/cosmpy" /></a>.
+
+[comment]: <> (## Dependencies)
+
+[comment]: <> (CosmPy works with any version of Python >= 3.7.)
+
+[comment]: <> (## Platforms)
+
+[comment]: <> (CosmPy can be used in Linux, MacOS, Windows)
+
+## Repository
+
+```
+https://github.com/fetchai/cosmpy`
+```
+
+## To contribute
+
+Clone the repo:
+
+``` bash
+git clone https://github.com/fetchai/cosmpy.git --recursive && cd cosmpy
+```
+
+Set up development environment:
+
+``` bash
+make new_env_dev
+```
+
+This creates a new `pipenv` virtual environment and installs the development dependencies.
+
+Enter the virtual environment: 
+
+``` bash
+pipenv shell
+```
+     

docs/query-balance.md

@@ -0,0 +1,15 @@
+# ️Querying balance
+
+To query the balance of an account using a [`LedgerClient`](connect-to-network.md) object `ledger_client`:
+
+```python
+balance = ledger_client.query_bank_balance('fetch1h2l3cnu7e23whmd5yrfeunacez9tv0plv5rxqy')
+```
+
+`fetch1h2l3cnu7e23whmd5yrfeunacez9tv0plv5rxqy` in the above code is the account's address.
+
+By default, this will query the fee denomination that is in the network config associated with `ledger_client`. To explicitly specify the denomination value:
+
+```python
+balance = ledger_client.query_bank_balance('cosmos1h2l3cnu7e23whmd5yrfeunacez9tv0plv5rxqy', denom='uatom')
+```

docs/send-tokens.md

@@ -0,0 +1,12 @@
+# Sending Tokens
+
+Once you have your [`wallet`](wallets-and-keys.md) configured, you can send transactions to the network. The `LedgerClient` object provides useful utilities to do common operations. The following example shows how to send `10` `atestfet` to another address:
+
+```python
+destination_address = 'fetch1h2l3cnu7e23whmd5yrfeunacez9tv0plv5rxqy'
+
+tx = ledger_client.send_tokens(destination_address, 10, "atestfet", wallet)
+
+# block until the transaction has been successful or failed
+tx.wait_to_complete()
+```