fix: review remarks

oasisprotocol · Jan 14, 2025 · 12512b6 · 12512b6
1 parent 0f82ce7
commit 12512b6
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 24 deletions.
diff --git a/docs/develop/README.mdx b/docs/develop/README.mdx
@@ -1,25 +1,27 @@
 ---
-description: Build DApps on Sapphire
+description: Develop new DApps on Sapphire
 ---
 
-# Build
+# Develop
 
 As Sapphire is EVM-compatible, you can use the same dev tooling as you would
 when building on Ethereum. Additionally, we build tools to support you in
 creating secure and confidential DApps.
 
-Feel free to check out the [concept] page to get a better understanding of the
+Feel free to check out the [Concept] page to get a better understanding of the
 transaction flow and the contract state.
 
-[concept]: ./concept.mdx
+[Concept]: ./concept.mdx
 
 ## Contract Development
 
 Sapphire is programmable using any language that targets the EVM, such as Solidity,
 Fe or Vyper. If you prefer to use an Ethereum framework like Hardhat or Foundry,
 you can also use those with Sapphire; all you need to do is set your Web3 gateway URL.
 You can find the details of the Oasis Sapphire Web3 endpoints
-[here](../network.mdx#rpc-endpoints).
+on the [Network information] page.
+
+[Network information]: ../network.mdx#rpc-endpoints
 
 ### Features
 
@@ -37,21 +39,19 @@ You can find the details of the Oasis Sapphire Web3 endpoints
 
 ## Frontend Development
 
-To connect your frontend to your smart contracts, see the [browser] chapter.
+To connect your frontend to your smart contracts, see the [Browser] chapter.
 
-[browser]: ./browser.md
+[Browser]: ./browser.md
 
-:::info More Frontend Frameworks
+### More Frontend Frameworks
 
 We support the common frontend libraries with the v2 client:
 
-| Framework               | Package                                           | API-Doc           | Github                  |
+| Framework               | Package                                           | API               | GitHub                  |
 | ----------------------- | ------------------------------------------------- | ----------------- | ----------------------- |
-| **[Ethers v6][ethers]** | [@oasisprotocol/sapphire-ethers-v6][ethers-npmjs] | [API][ethers-api] | [Github][ethers-github] |
-| **[Viem][viem]**        | [@oasisprotocol/sapphire-viem-v2][viem-npmjs]     | [API][viem-api]   | [Github][viem-github]   |
-| **[Wagmi][wagmi]**      | [@oasisprotocol/sapphire-wagmi-v2][wagmi-npmjs]   | [API][wagmi-api]  | [Github][wagmi-github]  |
-
-:::
+| **[Ethers v6][ethers]** | [@oasisprotocol/sapphire-ethers-v6][ethers-npmjs] | [API][ethers-api] | [GitHub][ethers-github] |
+| **[Viem][viem]**        | [@oasisprotocol/sapphire-viem-v2][viem-npmjs]     | [API][viem-api]   | [GitHub][viem-github]   |
+| **[Wagmi][wagmi]**      | [@oasisprotocol/sapphire-wagmi-v2][wagmi-npmjs]   | [API][wagmi-api]  | [GitHub][wagmi-github]  |
 
 [ethers]: https://docs.ethers.org/v6/
 [ethers-npmjs]: https://www.npmjs.com/package/@oasisprotocol/sapphire-ethers-v6
@@ -71,11 +71,11 @@ We support the common frontend libraries with the v2 client:
 If you want to connect and execute transactions from your backend.
 Sapphire has three clients in different programming languages:
 
-| Language        | Package                                            | API-Docs      | Github              |
+| Language        | Package                                            | API           | GitHub              |
 | --------------- | -------------------------------------------------- | ------------- | ------------------- |
-| **Javascript**  | [@oasisprotocol/sapphire-paratime][sapphire-npmjs] | [API][js-api] | [Github][js-github] |
-| **Go**          | [@oasisprotocol/sapphire-paratime][go-pkg]         | [API][go-api] | [Github][go-github] |
-| **Python**      |                                                    | [API][py-api] | [Github][py-github] |
+| **Javascript**  | [@oasisprotocol/sapphire-paratime][sapphire-npmjs] | [API][js-api] | [GitHub][js-github] |
+| **Go**          | [@oasisprotocol/sapphire-paratime][go-pkg]         | [API][go-api] | [GitHub][go-github] |
+| **Python**      |                                                    | [API][py-api] | [GitHub][py-github] |
 
 [sapphire-npmjs]: https://www.npmjs.com/package/@oasisprotocol/sapphire-paratime
 [go-pkg]: https://pkg.go.dev/github.com/oasisprotocol/sapphire-paratime/clients/go

diff --git a/docs/develop/concept.mdx b/docs/develop/concept.mdx
@@ -5,9 +5,9 @@ description: Sapphire concepts
 import DocCard from '@theme/DocCard';
 import {findSidebarItem} from '@site/src/sidebarUtils';
 
-# Concept
+# Concepts
 
-### Transactions & Calls
+## Transactions & Calls
 
 {/*-- https://github.com/oasisprotocol/docs/blob/455980674563cad92ff1e1b62a7a5f2d4d6809f0/docs/general/images/architecture/client-km-compute.svg -->*/}
 ![Client, Key Manager, Compute Node diagram](../../../general/images/architecture/client-km-compute.svg)
@@ -53,7 +53,7 @@ client's call data were originally encrypted or not.
 
 </details>
 
-### Contract State
+## Contract State
 
 The Sapphire state model is like Ethereum's except for all state being encrypted
 and not accessible to anyone except the contract. The contract, executing in an
@@ -81,7 +81,7 @@ patterns may be done by using an ORAM implementation.
 Contract state may be made available to third parties through logs/events, or
 explicit getters.
 
-### Contract Logs
+## Contract Logs
 
 Contract logs/events (e.g., those emitted by the Solidity `emit` keyword)
 are exactly like Ethereum. Data contained in events is *not* encrypted.
@@ -98,3 +98,7 @@ obviously problematic if you're writing a confidential token. What you can
 do instead is fork that contract and remove the offending emissions.
 
 :::
+
+## See also
+
+<DocCard item={findSidebarItem('/build/sapphire/ethereum')} />
diff --git a/docs/ethereum.md → docs/ethereum.mdx b/docs/ethereum.md → docs/ethereum.mdx
@@ -2,6 +2,9 @@
 description: Differences to Ethereum
 ---
 
+import DocCardList from '@theme/DocCardList';
+import {findSidebarItem} from '@site/src/sidebarUtils';
+
 # Sapphire vs Ethereum
 
 Sapphire is generally compatible with Ethereum, the EVM, and all the user and
@@ -87,3 +90,7 @@ after the block is proposed and **the network will halt, until the required
 number signatures are provided**. This means that you can rest assured that any
 validated block is final. As a consequence, the cross-chain bridges are more
 responsive yet safe on the Oasis Network.
+
+## See also
+
+<DocCard item={findSidebarItem('/build/sapphire/develop/concept')} />
diff --git a/docs/examples.mdx b/docs/examples.mdx
@@ -1,5 +1,5 @@
 ---
-description: Examples build with Sapphire
+description: Examples built with Sapphire
 ---
 
 # Examples
@@ -42,7 +42,7 @@ Onchain transaction generation and signing [example][onchain-signer].
 
 :::
 
-Find more examples on [playground.oasis.io].
+Find more examples, including the unofficial ones, on [playground.oasis.io].
 
 [rng-example]: https://github.com/oasisprotocol/demo-oasisswag
 [voting-example]: https://github.com/oasisprotocol/dapp-blockvote