uniswap / docs

📓 Uniswap V3 docs website

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?
  • In this case, contracts
• 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?
  • Yes I did using the guides below

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:
  • Start url from updated website
  • Sitemap url from updated website: eg for docs: https://docs.uniswap.org/sitemap.xml
  • Use "v3-docs" as the index name
• 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.

docs's Issues

mobile version has sidebar button in wrong place / conflicting with navbar button

Guides are not on V3

Needs favicon changed, header sizes adjusted, and font that reflects the current .org

dark mode makes parameter boxes not visible

Docs for Liquidity Mining

Draft how to guides for Liquidity Mining. I would suggest two:

• User Guide: how to participate
  • how to join a liquidity mining program (either with an existing LP position, or by creating a new LP position)
  • how rewards are calculated
  • how to claim (what happens if you claim after the end time)
• Dev Guide: how to create a Liquidity Mining program
  • lots of little details to know about

reference: https://docs.google.com/document/d/1DBxUVmp2Qq-JZYNe0XloZ968tdVO8SNGD83sEMOUu3A/edit#

Link the swaps example from the landing page

Redirect old docs URLs to new URL

• Connor to create the URL mapping
• Jordan will implement the redirect in Gatsby
• Will to monitor traffic flow after launch

Developer research study to understand developer journeys

Create zendesk to host L2 user guide

Implement a Swap SDK Guide

liquidity provider user guide page - "deposit amounts" section has wrong info

https://docs.uniswap.org/concepts/introduction/liquidity-user-guide#5-deposit-amounts currently says:

Entering a value in one of the 'Select Deposit Amounts' modules will automatically fill the remaining module on a 50/50 split basis. As an example, if an LP is depositing into the ETH-DAI pool and the ETH price is 2,000 DAI per ETH, a deposit amount of 1 ETH will be automatically matched with 2,000 DAI.

An LP may choose to deviate from a 50/50 portfolio balance from the outset. LPs can adjust their exposures by returning to the previous step — Select Price Range — and modifying either upper or lower bound.

But nowhere in the preceding "select price range" section did it mention/assume an example price range that is geometrically-equidistance from the current price (a prerequisite for the 50/50 split quoted above).

I will try to rewrite some of these, to be consistent/correct in the example/assumptions, and then submit a PR.

Documentation Link to migration contract missing

On this v2 to v3 migration guide, the copy suggests there is a link to a migration contact, but the link is missing.

"The migration contract may be viewed here."

I would expect here to be a hyperlink to the contract but it does not. I would do a PR but I don't want to link to the incorrect version.

docgen does not render `view`, `pure`,`override`, or modifiers

navbar links fallback to most recent version instead of current version

Guessing the solution is in activeBaseRegex: within the docusaurus.config navbar item section

issue is a matter of client-side routing as specified below:

https://v2.docusaurus.io/docs/api/themes/configuration#navbar

Fix internal linking on the docs

Update Add Liquidity guide

The new Add Liquidity UX is almost ready and it links out to user guide: https://docs.uniswap.org/concepts/introduction/liquidity-user-guide#4-set-price-range

We should update the ux mocks in that guide with the new UX

Directory specific navbar dropdowns open new tabs

This should be fixed via fixing the wholistic version dropdown which will deprecate the tab specific dropdowns

Needs reference code to have spacing reflect contract style

will need to be manual if docgen cant do it

SDK docgen template (Handlebars.js) needs to be rewritten

https://typedoc.org/

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

The typescript template for generating markdown pages is generating too much unhelpful content in the pages, and is organized (imo) in an unintuitive way. The template is written in Handlebars, and is broken into a bunch of libraries and was pretty confusing to me, so this will take some time.

Its possible that the better option is to manually create the SDK reference docs and abandon the docgen process, but that path has its own issues.

Create github actions in periphery and core that runs docgen script

Contribution guidelines for docs

view all results in algolia search not rendering

SC Liquidity guide

• notes are ready for connor to write copy

Fix layout at narrow width

At a narrow width just before switching to Mobile layout, a bunch of elements fall out of place.

Take down old add liquidty guide

Please take down https://docs.uniswap.org/protocol/concepts/introduction/liquidity-user-guide

because we published the updated version in the Help Center

Need glossary of core error codes

Update add Liquidity user guide

• Maggie is creating new gifs
• Will or Teo to write new copy for selecting price range based on distribution chart. Also explain auto fee tier.
• Migrate to the new Intercom site

Write copy for Swap guide

More complex liquidity code example

disable header `#` link because its useless

Liquidity Guide code samples (add, collect fees, remove)

edit on github links do not direct to correct files

Publish How To guides for Layer 2

• User guide:
  • what is an L2
  • how to use on uniswap
  • things to know: bridge, withdraw time, etc
• Dev Docs
  • how to interact with Uniswap v3 on each L2
  • contract addresses
    • arbitrum addresses: Uniswap/deploy-v3@0107b4b

Past SDK reference versions should be updated with correct reference code

Past SDK reference docs are out of date. The past versions should be updated to be aligned with the npm package versions, with the correct content represented therein.

Docs site versioning toggle

Complete Simple Swap Example Contract

PR here #126

Some back linking may be dead

Fixable by going through all V2 and V1 pages and testing each backlink. I've fixed most but some may remain

create staker contract reference

Needs .org colors and syntax highlighting

Uni

(Homepage): fix faq and protocol overview links

each reference page needs to link to the correct contract in the v3 core repo

Release landing page

blocking release of the versioning toggle #111

V3 https://docs.uniswap.org/ Edit references to non existing URL

V3 https://docs.uniswap.org/ Edit references to non existing URL
https://github.com/uniswap/uniswap-docs/docs/V3/concepts/introduction/landing.md

Update governance contract documentation

The GovernorAlpha contract was updated recently per https://www.fish.vote/proposal/0xA13a5a31b891F3DA7074b740B694769BD0f1bb23. I'd like to request that the documentation on these two pages is updated to reflect the new contract address, 0xc4e172459f1e7939d522503b81afaac1014ce6f6

reference missing descriptions of swap parameters

https://docs.uniswap.org/protocol/reference/periphery/interfaces/ISwapRouter

reference doc does not have the natspec descriptions of the swap parameters, only the code blocks of the structs

SDK liquidity guide

Write copy for v1 & v2 landing pages

Switch Algolia to automatic mode

Swap functions documentation on input has broken markdown

The markdown is broken:

https://docs.uniswap.org/reference/core/UniswapV3Pool