Skip to content

Latest commit

 

History

History
162 lines (117 loc) · 7.28 KB

README.md

File metadata and controls

162 lines (117 loc) · 7.28 KB
Raw

Uniswap Documentation

This web application contains all documentation for Uniswap products. It is built using Docusaurus 2, a modern static website generator.

Project Layout

Uniswap documentation is broken down into four sections:

  • Concepts - General Uniswap information or concepts useful for using Uniswap products, such as Liquidity and Fees
  • Contracts - Uniswap smart contracts such as the V3 Contracts or Permit2
  • SDKs - Uniswap integrations such as the v3-sdk and the Swap Widget
  • APIs - The Uniswap APIs such the Subgraph API

Each item in a section should include the following:

  • Overview
  • Guides
  • Technical Reference

Adding Documentation

After deploying your change, please make sure you update the search indices if a new file was added as part of the change

Overview

A product overview should address points such as:

  • What are the high level components of the product?
  • What what is the high level functionality the product offers?
  • Where does the source code of the product live?
  • Where does the code artifact live (eg npm) and how does someone integrate with it?

A good example is the V3 Smart Contracts.

Guides

Guides should follow the Principles of a Good Guide:

  • A guide corresponds to a reusable piece of code that demonstrates a single concept in the Uniswap ecosystem.
  • Guides have three parts:
    1. An introduction that explains the concept that the piece of code implements and a summary of what the guide will cover and result in.
    2. A step-by-step walkthrough of each line of the example code
    3. An output or end state that users can test against what they’re seeing to know if they implemented correctly
  • Guides do not show source code snippets that should not be included in the example (IE using snippets from a source contract to explain how to integrate with it). If a guide needs to reference an external piece of code it should link to the source code or technical reference.
  • We keep Links and References only at the bottom of pages and reference them using footnotes to keep distractions at a minimum
  • Our goal is to have the developer build something within 10 minutes per guide but also provide the option for a deep dive by providing references to extra content.
  • Guides should end with a transition to the next one, recommendations and real world projects examples
  • Each guides should refer to a code example in our example-repo
  • Guides should be standalone pieces
  • Use the least dependencies as possible
  • Input changes (eg address, tokens, amounts) should be in the code

By implementing these consistent principles Uniswap will have docs that are easy to understand and produce reusable code for its community.

A good example is the V3 SDK Guides.

Technical References

This should contain the technical reference for the exported interfaces. A good example is the V3 SDK. These files can be created using the guides below.

Contributing to Uniswap Docs

Guidelines

Contributing to the docs site is a great way to get involved in the dev community and help other developers along the way! Check out our guidelines here.

Checklist for adding a new product

  • Did I pick the right section for the product?
  • Did I create the product folder?
  • Did I introduce any new concepts? If so add under /concepts/<category_name><product_name>
  • Did I include an Overview of the product under <category_name>/<product_name>/overview ?
  • Did I include Guides of the product under <category_name>/<product_name>/guides ?
  • Did I include Technical Reference of the product under <category_name>/<product_name>/reference ?
  • Did I give a descriptive name/id to each document? This is important because that shows up in the URL
  • Did I open a PR using the the contributing guidelines?
  • Did I update the search indices after my change was deployed?

Checklist example

Let's walk through an example by considering the Permit2 smart contract:

  • Did I pick the right section for the product?
  • Did I create the product folder?
    • In this case, yes
  • Did I introduce any new concepts?
    • No
  • Did I include an Overview of the product under /contracts/permit2/overview ?
    • Yes, I did add them here
  • Did I include Guides of the product under contracts/permit2/guides ?
    • No, they should be added here
  • Did I include Technical Reference of the product under contracts/permit2/reference ?
    • Yes I added them here
  • Did I open a PR using the the Contributing guidelines?
    • Yes
  • Did I update the search indices after my change was deployed?

How to create a Technical Reference

How to generate markdown files from solidity Natspec comments

Install solidity doc gen npm install solidity-docgen

Get the correct compiler version npm install -D solc-0.7@npm:[email protected]

Put the updated template contract.hbs in a /templates folder under the same directory as /contracts that you want to generate

Run npx solidity-docgen --solc-module solc-0.7 -t ./templates

How to generate markdown files from typescript comments

npm install --save-dev typedoc typedoc-plugin-markdown

Depending on how your project was created, you might have to install Typescript: npm install --save-dev typescript

npx typedoc --out <docs> src/index.ts

You might have to use the --skipErrorChecking flag to the typedoc command for cases where types are fetched during transpile time, such as contract ABIs.

See https://www.npmjs.com/package/typedoc-plugin-markdown for details.

How to Update search indices with algolia

  • Create an .env file with APPLICATION_ID and the API_KEY (write access). If you don't have those, one for the Engineering Managers should be able to help you.
  • Edit config.json file if needed:
  • Install and start running Docker Desktop
  • Install jq brew install jq
  • Run docker run -it --env-file=.env -e "CONFIG=$(cat ./config.json | jq -r tostring)" algolia/docsearch-scraper

Installation

yarn install

Local Development

yarn run start

This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.

Clear cache

yarn docusaurus clear

Build

yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Deployment

The application automatically deployed to production using Vercel upon merge into main.