docs icon indicating copy to clipboard operation
docs copied to clipboard

Add Bonadocs Widget to lido.md

Open staa99 opened this issue 2 years ago • 0 comments

Intro

The goal of this PR is to supercharge Lido’s documentation by adding interactive widgets that make it possible to interact with the protocol contracts directly inside the documentation. This results in better developer experience (DX) leading to an increase in protocol and app integrations for Lido.

Demo: https://www.loom.com/share/9affc4deecde438cb108efb4bd188c1c

Contributors

@staa99 and @Atanda1 are current and former contributors to other web3 products and tools including Infura, The Graph, and Ethers.

Outline

When reading the documentation, the explanation of the protocol contracts is great. However, developers have to setup a basic testing environment to interact with the contracts to better understand the behavior. The widget eliminates this by enabling developers to interact with the contract methods directly within the documentation. This greatly reduces integration time and the context switching that would otherwise be required, making Lido more developer-friendly.

We are looking to integrate the widget in the documentation pages through open source contributions. The widget will replace the function code sections with an interactive interface that enables developers to interact with the protocol function being described. In some of the guides, there are descriptions of workflows that involve a more involved operation than simply calling a single contract function. Adding the widget to such guides will help developers understand the docs better.

Technical Information

The widget is an open-source library: @bonadocs/widget.

The list of protocol smart contracts, deployment addresses, ABIs, and other widget configuration are stored on IPFS at the URI ipfs://bafkreib3rg6fnaq3j33js7zkoc67wn6lwtyltkw2rz2xxjs4fjgo4bdgwu. We chose to store the data on IPFS to guarantee immutability of the contract information and addresses, preserving the safety of the widget.

Summary of Changes

We installed the widget using

    yarn add @bonadocs/widget

Then we registered the widget in the MDXComponents at src/theme/MDXComponents.js. The file did not exist so we created it. It allows us to just use <BonadocsWidget /> within the documentation without having to import it in each markdown file.

import React from 'react'
import MDXComponents from '@theme-original/MDXComponents'
import BonadocsWidget from '@bonadocs/widget'

export default {
  ...MDXComponents,
  BonadocsWidget,
}

For this PR, we have only updated docs/contracts/lido.md. If this gets approved, we will proceed to add the widget to other pages. For each solidity function on the page, we replaced the static code block with the widget. For example, the submit function looks like this:

<BonadocsWidget widgetConfigUri="ipfs://bafkreib3rg6fnaq3j33js7zkoc67wn6lwtyltkw2rz2xxjs4fjgo4bdgwu" contract="Lido" functionKey="submit(address)" />

The widgetConfigUri property specifies the configuration for the widget. contract specifies the name of the contract as defined in the linked collection from the widget config, and functionKey specifies the function being described.

P.S: This contribution is sponsored by [Arbitrum X Questbook grant](https://www.questbook.app/dashboard/?grantId=0x706bc8efecb6002f00a052fe5688d0eb89ea45f4&chainId=10&proposalId=0x463&role=builder) through [Bonadocs](https://github.com/bonadocs) - [Consensys Fellowship startup](https://consensys.io/blog/introducing-the-first-cohort-of-the-consensys-fellowship-program-for-web3).

staa99 avatar Jan 08 '24 11:01 staa99