Merge pull request #963 from Concordium/sc-doc-improvements

SC documentation improvements

Author: dg-concordium

README.md

@@ -316,6 +316,18 @@ Images must have :alt: text for accessibility. Generally, image width is 100%. F
 
 GIFs can be inserted but should only be used when it gives clarity to more complex actions. When using GIFs, the :alt: text is StreamPlayer and :align: is center.
 
+### Videos
+
+To embed a video in a topic, use the `raw` directive.
+
+``` restructuredtext
+   .. raw:: html
+
+      <iframe src="https://www.youtube.com/embed/0UIyAlZjvLg?si=D0lguDkUjiHCKLcu" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+```
+
+Remove any fixed dimensions from the embed link information you copied from the video source. The sizing is handled in the stylesheet.
+
 ## Preview
 
 For non-technical users that might not want to install the tools above, you can request a preview in the GitHub pull request. The preview is added as a comment in the pull request and opens as a web page.

source/_static/css/style.css

@@ -136,6 +136,13 @@ a.current.reference.internal:hover{
     padding-right: 0.5em;
 }
 
+/*Video handling*/
+
+iframe {
+    width: 100%;
+    aspect-ratio: 16 /9;
+ }
+
 /*Topnav styling*/
 .navbar{
     position: fixed;

source/mainnet/conf.py

@@ -368,6 +368,8 @@
     "./net/resources/legal": "net/resources/terms-and-conditions.html",
     "./en/mainnet/smart-contracts/onboarding-guide-solana-developers/index": "en/mainnet/smart-contracts/onboarding-guide-solana-developers/overview.html",
     "./net/references/grpc": "net/references/grpc2.html",
+    "./en/mainnet/smart-contracts/guides/contract-testing-guides": "./en/mainnet/smart-contracts/guides/integration-test-contract",
+    "./en/mainnet/smart-contracts/best-practices/index": "./en/mainnet/smart-contracts/best-practices/development",
 }
 
 # -- Tags that enables the .. only option ----------------

source/mainnet/net/guides/dapp-examples.rst

@@ -7,6 +7,8 @@ dApp examples
 
 Select an example to see more information about it, such as a hosted dApp for you to try, links to tutorials, repositories, and more.
 
+Starting a new project on the Concordium blockchain? Have a look at the `dApp starter template <https://github.com/Concordium/concordium-dapp-starter>`__!
+
 .. dropdown:: Piggy bank
 
     `Demo front end <https://piggybank.testnet.concordium.com>`__ where you can try the functionality on Concordium's testnet
@@ -84,7 +86,8 @@ Select an example to see more information about it, such as a hosted dApp for yo
 .. dropdown:: Wallet test bench
 
     This tool is for testing wallets and shows a great overview of the available interactions between wallets and front end.
-    Deploy and initialize scenarios are available on the browser wallet (will be implemented in the mobile wallets in the future).
+
+    Deploy and initialize scenarios are available on the |bw|.
 
     `Demo front end <https://wallet-test-bench.testnet.concordium.com/>`__ where you can test wallet interactions
 

source/mainnet/net/guides/developer-page.rst

@@ -7,60 +7,61 @@ Developer resources
 
 The following developer resources help you get started developing on the Concordium network.
 
-Official resources
-==================
+All of our repositories are on `GitHub <https://github.com/Concordium>`__.
 
-- See :ref:`Node setup<node-requirements>` for information about the requirements to run a node and the available platforms for nodes.
+.. dropdown:: Standards
 
-- See :ref:`SDKs and APIs<sdks-apis>` for links to SDKs and APIs for development
+    - `Concordium standards and updates <https://proposals.concordium.software/>`_
 
-- See :ref:`Smart contracts <introduction>` for general information about smart contracts
-
-    - `Smart contract libraries <https://crates.io/crates/concordium-std>`_
+    - `CIS-0 standard detections <https://proposals.concordium.software/CIS/cis-0.html>`_
 
-    - To ease deployment and initialization, you can use the `Smart contract deploy and initialize tool <https://sctools.mainnet.concordium.software/>`__ instead of the process below. It works with the |bw| to deploy and initialize smart contracts to Mainnet and Testnet.
+    - `CIS-2 token standard <https://proposals.concordium.software/CIS/cis-2.html>`_
 
-- `GitHub <https://github.com/Concordium>`_
+    - `CIS-3 sponsored transaction standard <https://proposals.concordium.software/CIS/cis-3.html>`_
 
-- `Concordium standards and updates <https://proposals.concordium.software/>`_
+.. dropdown:: Nodes
 
-    - `CIS-0 standard detections <https://proposals.concordium.software/CIS/cis-0.html>`_
+    See :ref:`Node setup<node-requirements>` for information about the requirements to run a node and the available platforms for nodes.
 
-    -  Applicable for Smart contracts v1:
+    For testing purposes, a node is available on testnet to use when testing smart contracts and dApps. You can use this node for API calls of chain methods only with gRPC v2 and gRPC web. The address is node.testnet.concordium.com on port 20000 (gRPCv2 and gRPC-web). You can use this node for API calls of *chain methods only*. This node is maintained by Concordium, but Concordium does not guarantee availability. The status of this node is available on the `Testnet status page <https://status.testnet.concordium.software>`__.
 
-        - `CIS-2 token standard <https://proposals.concordium.software/CIS/cis-2.html>`_
+.. dropdown:: SDKs and APIs
 
-        - `CIS-3 sponsored transaction standard <https://proposals.concordium.software/CIS/cis-3.html>`_
+    The following SDKs and APIs exist for developing on the Concordium network.
 
-- See :ref:`How to create proofs for dApps and services <create-proofs>` for information about how to write statements that interact with Concordium wallets.
+    - `Concordium Rust SDK <https://github.com/Concordium/concordium-rust-sdk>`_
+    - `Concordium Javascript (Node / Web) SDK <https://github.com/Concordium/concordium-node-sdk-js>`_
+    - `Concordium Java SDK <https://github.com/Concordium/concordium-java-sdk>`_
+    - `Concordium .NET (C#) SDK <https://github.com/Concordium/concordium-net-sdk>`_
+    - `Concordium Rosetta SDK <https://github.com/Concordium/concordium-rosetta>`_
+    - `Concordium go SDK <https://github.com/Concordium/concordium-go-sdk>`_
 
-- For information about how to create proofs to verify identity for dApps and services see :ref:`Create proofs<create-proofs>`.
+    There is also a :ref:`Concordium gRPC V2 API<grpc2-documentation>`. It is recommended to use the SDKs.
 
-- See :ref:`dApp examples<dapp-examples>` for a list of dApp examples and their resources.
+    The following NPM libraries are useful for building web-based dApps:
 
-- For testing purposes, a node is available on testnet to use when testing smart contracts and dApps. You can use this node for API calls of chain methods only with gRPC v2 and gRPC web. The address is node.testnet.concordium.com on port 20000 (gRPCv2 and gRPC-web). You can use this node for API calls of *chain methods only*. This node is maintained by Concordium, but Concordium does not guarantee availability. The status of this node is available on the `Testnet status page <https://status.testnet.concordium.software>`__.
+    - `@concordium/web-sdk <https://www.npmjs.com/package/@concordium/web-sdk>`_ (for interacting with a chain).
+    - `@concordium/ccd-js-gen <https://www.npmjs.com/package/@concordium/ccd-js-gen>`_ (for generating smart contract clients in JavaScript).
+    - `@concordium/react-components <https://www.npmjs.com/package/@concordium/react-components>`_ (for React projects).
+    - `@concordium/wallet-connectors <https://www.npmjs.com/package/@concordium/wallet-connectors>`_ (for connecting to wallets in non-React projects).
 
-- The `VSCode extension <https://marketplace.visualstudio.com/items?itemName=Concordium.concordium-smart-contracts>`__ can help you develop Concordium smart contracts. The extension sets up the editor for development, installs the ``cargo-concordium`` smart contract development tool for all supported platforms, and provides commands in the editor for the essential workflows, such as building and testing smart contracts.
+.. dropdown:: Smart contracts
 
-You can watch a video about how to use the VSCode extension.
+    See :ref:`Smart contracts <introduction>` for general information about smart contracts, including a list of the available :ref:`smart contract development tools<sc-dev-tools>` to make creation, testing, and deployment easier.
 
-.. image:: https://img.youtube.com/vi/9qjcsGDeveg/maxresdefault.jpg
-    :alt: video about smart contract lifecycle
-    :target: https://www.youtube.com/watch?v=9qjcsGDeveg
+    `The main library for developing smart contracts can be found on crates.io <https://crates.io/crates/concordium-std>`__.
 
-- An external `transaction logger <https://github.com/Concordium/concordium-transaction-logger>`_ service
+.. dropdown:: Proofs
 
-Concordium Proof Explorer
--------------------------
+    See :ref:`How to create proofs for dApps and services <create-proofs>` for information about how to write statements that interact with Concordium wallets.
 
-If you want to familiarize yourself with how proofs work and can be constructed, you can use the `Concordium Proof Explorer <https://web3id-proof-explorer.testnet.concordium.com/>`__ to create proofs and send them to a |bw| to see how they interact with account credentials and verifiable credentials. The Concordium Proof Explorer works on Testnet. You can use the `Web3Id Issuer Front End <https://web3id-issuer-frontend.testnet.concordium.com/>`__ to create verifiable credential to test with the proof explorer.
+    For information about how to create proofs to verify identity for dApps and services see :ref:`Create proofs<create-proofs>`.
 
-.. _example-dapps:
+    If you want to familiarize yourself with how proofs work and can be constructed, you can use the `Concordium Proof Explorer <https://web3id-proof-explorer.testnet.concordium.com/>`__ to create proofs and send them to a |bw| to see how they interact with account credentials and verifiable credentials. The Concordium Proof Explorer works on Testnet. You can use the `Web3Id Issuer Front End <https://web3id-issuer-frontend.testnet.concordium.com/>`__ to create verifiable credential to test with the proof explorer.
 
-Example dApps
--------------
+.. dropdown:: dApps
 
-Concordium has a selection of example dApps that you can clone to make your own dApps or for inspiration. Additionally, all of these example dApps are hosted so you can try the functionality on Concordium's testnet.
+    Concordium has a selection of example dApps that you can clone to make your own dApps or for inspiration. Additionally, all of these example dApps are hosted so you can try the functionality on Concordium's testnet.
 
     - Piggy bank: :ref:`Piggy bank tutorial<piggy-bank>` / `Piggy bank dApp <https://piggybank.testnet.concordium.com>`__
     - wCCD: :ref:`wCCD tutorial<wCCD>` / `wCCD dApp <https://wccd.testnet.concordium.com/>`_
@@ -69,47 +70,53 @@ Concordium has a selection of example dApps that you can clone to make your own
     - eSealing: :ref:`eSealing tutorial<eSealing>` / `eSealing dApp <https://esealing.testnet.concordium.com>`_
     - signMessage: `Front end code <https://github.com/Concordium/concordium-dapp-examples/tree/main/signMessage>`__ / `signMessage dApp <http://signmessage.testnet.concordium.com/>`__
 
-.. _block-explorers:
+    For a full list of dApp examples and resources, see :ref:`dApp examples<dapp-examples>`.
 
-Block explorers
----------------
+    Starting a new project on the Concordium blockchain? Have a look at the `dApp starter template <https://github.com/Concordium/concordium-dapp-starter>`__!
 
-The following are links to the block, node, and status explorers.
+.. dropdown:: Block explorers and analytics
 
-Concordium status pages
-^^^^^^^^^^^^^^^^^^^^^^^
+    .. _block-explorers:
 
-For information about the status pages, see :ref:`Status pages<dashboards>`.
+    The following are links to the block, node, and status explorers.
 
-    - `Mainnet status page <https://status.mainnet.concordium.software>`_
+    **Concordium status pages**
+
+    - `Mainnet status page <https://status.mainnet.concordium.software>`__
 
     - `Testnet status page <https://status.testnet.concordium.software>`__
 
-CCDScan
-^^^^^^^
+    For information about the status pages, see :ref:`Status pages<dashboards>`.
 
-For information about CCDScan, see :ref:`CCDScan<ccd-scan>`.
+    **CCDScan**
 
     - `CCDScan <https://ccdscan.io>`_
 
-Grafana® node dashboard
-^^^^^^^^^^^^^^^^^^^^^^^
+    For information about CCDScan, see :ref:`CCDScan<ccd-scan>`.
 
-For node runners using Grafana, Concordium provides a node performance dashboard using the exposed Prometheus metrics. You can `download it from the Grafana marketplace <https://grafana.com/grafana/dashboards/18983-concordium-node-external/>`__.
+    **Grafana® node dashboard**
 
-Social media and support
-------------------------
+    For node runners using Grafana, Concordium provides a node performance dashboard using the exposed Prometheus metrics. You can `download it from the Grafana marketplace <https://grafana.com/grafana/dashboards/18983-concordium-node-external/>`__.
 
-- `Discourse <https://support.concordium.software/>`_
+    **Transaction logger**
 
-- `Telegram <https://t.me/concordium_official>`_
+    An external `transaction logger <https://github.com/Concordium/concordium-transaction-logger>`_ service
 
-- `Discord <https://discord.com/invite/xWmQ5tp>`_
+    **Indexers**
 
-Community resources
-===================
+    See :ref:`Indexers<indexers-intro>` for more information.
+
+.. dropdown:: Social media and support
+
+    - `Concordium's official support <https://support.concordium.software/>`_
+
+    - `Telegram <https://t.me/concordium_official>`_
+
+    - `Discord <https://discord.com/invite/xWmQ5tp>`_
+
+.. dropdown:: Community resources
 
--   `Block explorer built by a user in the Netherlands <https://concordium-explorer.nl/>`_
+    -   `Block explorer built by a user in the Netherlands <https://concordium-explorer.nl/>`_
 
 .. toctree::
     :hidden:

source/mainnet/net/guides/run-node-ubuntu.rst

@@ -10,7 +10,7 @@ You can also watch the video to learn how to run a node with Ubuntu.
 
 .. raw:: html
 
-   <iframe width="560" height="315" src="https://www.youtube.com/embed/lFqf0tgS_r0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+   <iframe src="https://www.youtube.com/embed/lFqf0tgS_r0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
 
 Prerequisites

source/mainnet/net/index.rst

@@ -41,12 +41,12 @@ index
 
    Introduction <../smart-contracts/general/introduction>
    Quick start guide <../smart-contracts/guides/quick-start>
-   Contract development guides <../smart-contracts/guides/contract-dev-guides>
-   Contract testing guides <../smart-contracts/guides/contract-testing-guides>
-   On-chain guides <../smart-contracts/guides/on-chain-index>
-   Best practices <../smart-contracts/best-practices/index>
    Ethereum developer onboarding <../smart-contracts/onboarding-guide-ethereum-developers/faq>
    Solana developer onboarding <../smart-contracts/onboarding-guide-solana-developers/overview>
+   Contract development guides <../smart-contracts/guides/contract-dev-guides>
+   Test contracts <../smart-contracts/guides/integration-test-contract>
+   On-chain guides <../smart-contracts/guides/on-chain-index>
+   Best practices <../smart-contracts/best-practices/development>
    References <../smart-contracts/references/index>
    V0 smart contracts <../smart-contracts-v0/sc-v0-rollup>
 

source/mainnet/net/indexers/intro.rst

@@ -1,3 +1,5 @@
+.. _indexers-intro:
+
 =================
 What are indexers
 =================

source/mainnet/net/indexers/subquery.rst

@@ -1,3 +1,5 @@
+.. _subquery:
+
 ========
 SubQuery
 ========

source/mainnet/net/nodes/run-node-ubuntu.rst

@@ -10,7 +10,7 @@ You can also watch the video to learn how to run a node with Ubuntu.
 
 .. raw:: html
 
-   <iframe width="560" height="315" src="https://www.youtube.com/embed/lFqf0tgS_r0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+   <iframe src="https://www.youtube.com/embed/lFqf0tgS_r0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
 
 Prerequisites

source/mainnet/smart-contracts-v0/guides/setup-tools.rst

@@ -46,9 +46,9 @@ The `VSCode extension <https://marketplace.visualstudio.com/items?itemName=Conco
 
 You can watch a video about how to use the VSCode extension.
 
-.. image:: https://img.youtube.com/vi/9qjcsGDeveg/maxresdefault.jpg
-    :alt: video about smart contract lifecycle
-    :target: https://www.youtube.com/watch?v=9qjcsGDeveg
+.. raw:: html
+
+   <iframe src="https://www.youtube.com/embed/9qjcsGDeveg?si=zGDkjMAdP5JjRMd8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
 
 Concordium software
 ===================

source/mainnet/smart-contracts/best-practices/development.rst

@@ -4,7 +4,8 @@
 Development best practices
 ==========================
 
-This document provides guidelines for developing smart contracts.
+This document provides guidelines for developing smart contracts, including best practices for smart contract development, audit, information about common pitfalls and security vulnerabilities, and how to avoid them.
+
 It starts with some general thoughts about smart contract development and then gives more details about writing smart contracts in Rust for Concordium.
 
 Mindset
@@ -15,7 +16,7 @@ Smart contract development involves many risks that do not show up in, for examp
 - the cost of mistakes is very high;
 - possibilities for fixing bugs are limited;
 - the area is evolving constantly, with new vulnerabilities being discovered regularly;
-- malicious parties deliberately try to break your contract, for example, to steal the funds from the contract account.
+- malicious parties deliberately try to break your contract, for example, to steal the funds from the contract or account.
 
 Therefore, it is not sufficient to defend your code against known vulnerabilities.
 You can think about smart contracts as mission-critical software, or software for embedded devices rather than a web application.
@@ -66,8 +67,7 @@ Concordium Rust Smart Contracts
 ===============================
 
 This section provides recommendations for developing smart contracts in Rust.
-See :ref:`introduction` for basic information.
-
+See :ref:`Introduction to smart contracts<introduction>` for basic information.
 
 .. _best-practices-code-structure: