docs: Various minor fixes

README.md

@@ -6,6 +6,7 @@
 [![Docker status][github-docker-badge]][github-docker-link]
 [![Release status][github-release-badge]][github-release-link]
 [![GoDev][godev-badge]][godev-link]
+[![GitBook][gitbook-badge]][gitbook-link]
 
 <!-- NOTE: Markdown doesn't support tables without headers, so we need to
 work around that and make the second (non-header) row also bold. -->
@@ -30,6 +31,8 @@ work around that and make the second (non-header) row also bold. -->
 [coveralls-link]: https://coveralls.io/github/oasisprotocol/oasis-core
 [godev-badge]: https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white
 [godev-link]: https://pkg.go.dev/github.com/oasisprotocol/oasis-core/go?tab=subdirectories
+[gitbook-badge]: https://img.shields.io/badge/gitbook-docs-007d9c?logo=read-the-docs&logoColor=white
+[gitbook-link]: https://docs.oasis.dev/oasis-core
 <!-- markdownlint-enable line-length -->
 
 ## Note
@@ -49,17 +52,19 @@ Read our [Security](SECURITY.md) document.
 
 ## Developer Documentation
 
-See our [developer documentation index](docs/index.md).
+See our [developer documentation index].
+
+[developer documentation index]: https://docs.oasis.dev/oasis-core
 
 ## Developing and Building the System
 
 See [a list of prerequisites] followed by [build instructions] and an example
 of [setting up a local test network with a simple runtime].
 
 <!-- markdownlint-disable line-length -->
-[a list of prerequisites]: docs/setup/prerequisites.md
-[build instructions]: docs/setup/building.md
-[setting up a local test network with a simple runtime]: docs/setup/oasis-net-runner.md
+[a list of prerequisites]: https://docs.oasis.dev/oasis-core/development-setup/build-environment-setup-and-building/prerequisites
+[build instructions]: https://docs.oasis.dev/oasis-core/development-setup/build-environment-setup-and-building/building
+[setting up a local test network with a simple runtime]: https://docs.oasis.dev/oasis-core/development-setup/running-tests-and-development-networks/oasis-net-runner
 <!-- markdownlint-enable line-length -->
 
 ## Directories

docs/oasis-node/rpc.md

@@ -10,11 +10,20 @@ including shutdown, of a node.**
 
 In order to support remote clients and different protocols (e.g. REST), a
 gateway that handles things like authentication and rate limiting should be
-used. We may provide implementations of such gateways in the future.
+used.
 
+{% hint style="info" %}
+An example of such a gateway is the [Oasis Core Rosetta Gateway] which exposes
+a subset of the consensus layer via the [Rosetta API].
+{% endhint %}
+
+<!-- markdownlint-disable line-length -->
 [consensus]: ../consensus/index.md
 [runtime]: ../runtime/index.md
 [submit transactions]: ../consensus/transactions.md#submission
+[Oasis Core Rosetta Gateway]: https://github.com/oasisprotocol/oasis-core-rosetta-gateway
+[Rosetta API]: https://www.rosetta-api.org
+<!-- markdownlint-enable line-length -->
 
 ## Protocol
 
@@ -29,6 +38,7 @@ by your local node at `/path/to/datadir/internal.sock` you can do:
 
 ```golang
 import (
+    // ...
     oasisGrpc "github.com/oasisprotocol/oasis-core/go/common/grpc"
 )
 
@@ -65,18 +75,37 @@ as the separator in method names, e.g., `/oasis-core.NodeControl/IsSynced`.
 
 The following gRPC services are exposed (with links to API documentation):
 
-* [Control] (`oasis-core.NodeController`)
-* [Consensus (client subset)] (`oasis-core.Consensus`)
-* [Consensus (light client subset)] (`oasis-core.ConsensusLight`)
-* [Staking] (`oasis-core.Staking`)
-* [Registry] (`oasis-core.Registry`)
-* [Scheduler] (`oasis-core.Scheduler`)
-* [Storage] (`oasis-core.Storage`)
-* [Runtime Client] (`oasis-core.RuntimeClient`)
-* [EnclaveRPC] (`oasis-core.EnclaveRPC`)
+* **General**
+  * [Node Control] (`oasis-core.NodeController`)
+* **Consensus Layer**
+  * [Consensus (client subset)] (`oasis-core.Consensus`)
+  * [Consensus (light client subset)] (`oasis-core.ConsensusLight`)
+  * [Staking] (`oasis-core.Staking`)
+  * [Registry] (`oasis-core.Registry`)
+  * [Scheduler] (`oasis-core.Scheduler`)
+* **Runtime Layer**
+  * [Storage] (`oasis-core.Storage`)
+  * [Runtime Client] (`oasis-core.RuntimeClient`)
+  * [EnclaveRPC] (`oasis-core.EnclaveRPC`)
 
 For more details about what the exposed services do see the respective
-documentation sections.
+documentation sections. The Go API also provides gRPC client implementations for
+all of the services which can be used after establishing a gRPC connection via
+the internal socket (multiple clients can share the same gRPC connection). For
+example in case of the consensus service using the connection we established in
+the previous example:
+
+```golang
+import (
+    // ...
+    consensus "github.com/oasisprotocol/oasis-core/go/consensus/api"
+)
+
+// ...
+
+cc := consensus.NewConsensusClient(conn)
+err := cc.SubmitTx(ctx, &tx)
+```
 
 <!-- markdownlint-disable line-length -->
 [Control]: https://pkg.go.dev/github.com/oasisprotocol/oasis-core/go/control/api?tab=doc#NodeController

docs/runtime/index.md

@@ -149,7 +149,9 @@ verify that all nodes have indeed computed the same result. As mentioned in case
 of discrepancies it will instruct nodes elected as _backups_ to repeat the
 computation.
 
-[cryptographic commitments]: ../../go/roothash/api/commitment
+<!-- markdownlint-disable line-length -->
+[cryptographic commitments]: https://pkg.go.dev/github.com/oasisprotocol/oasis-core/go/roothash/api/commitment?tab=doc
+<!-- markdownlint-enable line-length -->
 
 ### Storage Receipts
 

docs/setup/deploying-a-runtime.md

@@ -132,10 +132,14 @@ After confirmation, this command outputs a signed transaction in the
 `/tmp/runtime-example/register_runtime.tx` file. In the next step we will submit
 the transaction to complete the runtime registration.
 
-NOTE: when registering a runtime on a non-development network you will likely
+{% hint style="warning" %}
+**WARNING**
+
+When registering a runtime on a _non-development_ network you will likely
 want to modify default parameters. Additionally, since we are running this on
-a test network, we had to enable the `debug.dont_blame_oasis` and
+a debug network, we had to enable the `debug.dont_blame_oasis` and
 `debug.allow_test_keys` flags.
+{% endhint %}
 
 <!-- markdownlint-disable line-length -->
 [code reference]: https://pkg.go.dev/github.com/oasisprotocol/oasis-core/go/registry/api?tab=doc#Runtime
@@ -153,8 +157,7 @@ oasis-node consensus submit_tx \
 
 ## Confirm Runtime is Registered
 
-To confirm the runtime is registered use the
-`registry runtime list` command.
+To confirm the runtime is registered use the `registry runtime list` command.
 
 ```
 oasis-node registry runtime list \
@@ -171,8 +174,10 @@ Should give output similar to
 ```
 <!-- markdownlint-enable line-length -->
 
-Note: since we did not setup any runtime nodes, the runtime will get
-[suspended] until nodes for the runtime register.
+{% hint style="info" %}
+Since we did not setup any runtime nodes, the runtime will get [suspended] until
+nodes for the runtime register.
+{% endhint %}
 
 In the next step we will setup and run a runtime node.
 
@@ -183,8 +188,10 @@ In the next step we will setup and run a runtime node.
 We will now run a node that will act as a compute, storage and client node for
 the runtime.
 
-NOTE: in a real word scenario there would be multiple nodes running the runtime,
+{% hint style="info" %}
+In a real word scenario there would be multiple nodes running the runtime,
 each likely serving as a single type only.
+{% endhint %}
 
 Before running the node, gather the following data parameters and set up
 environment variables to simplify instructions.
@@ -230,8 +237,12 @@ oasis-node \
 ```
 <!-- markdownlint-enable line-length -->
 
-**NOTE: This also enables unsafe debug-only flags which must never be used in a
-production setting as they may result in node compromise.**
+{% hint style="danger" %}
+**WARNING**
+
+This also enables unsafe debug-only flags which must never be used in a
+production setting as they may result in node compromise.
+{% endhint %}
 
 Following steps should be run in a new terminal window.
 
@@ -301,8 +312,10 @@ oasis-node registry node list -a $ADDR -v | grep "$NODE_ID"
 oasis-node registry runtime list -a $ADDR -v
 ```
 
-NOTE: might need to wait few seconds for an epoch transition so that the node
+{% hint style="info" %}
+You might need to wait few seconds for an epoch transition so that the node
 is registered and runtime gets resumed.
+{% endhint %}
 
 [node control status command]: ../oasis-node/cli.md#status
 

docs/setup/single-validator-node-network.md

@@ -8,9 +8,13 @@ an Oasis Core environment followed by [build instructions] for the respective
 environment (non-SGX or SGX). The following sections assume that you have
 successfully completed the required build steps.
 
-**NOTE: These instructions are for a development-only instance, do not use them
+{% hint style="danger" %}
+**WARNING**
+
+These instructions are for a development-only instance, do not use them
 for setting up any kind of production instances as they are unsafe and will
-result in insecure configurations leading to node compromise.**
+result in insecure configurations leading to node compromise.
+{% endhint %}
 
 [prerequisites]: prerequisites.md
 [build instructions]: building.md
@@ -75,8 +79,12 @@ oasis-node genesis init \
   --registry.debug.allow_unroutable_addresses
 ```
 
-**NOTE: This enables unsafe debug-only flags which must never be used in a
-production setting as they may result in node compromise.**
+{% hint style="danger" %}
+**WARNING**
+
+This enables unsafe debug-only flags which must never be used in a
+production setting as they may result in node compromise.
+{% endhint %}
 
 ## Running the Node
 
@@ -93,8 +101,12 @@ oasis-node \
   --log.level debug
 ```
 
-**NOTE: This enables unsafe debug-only flags which must never be used in a
-production setting as they may result in node compromise.**
+{% hint style="danger" %}
+**WARNING**
+
+This enables unsafe debug-only flags which must never be used in a
+production setting as they may result in node compromise.
+{% endhint %}
 
 ## Using the Node CLI