Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: refine README with improved structure and content updates #789

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: refine README with improved structure and content updates #789

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
316 changes: 215 additions & 101 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,162 +1,276 @@
# Uniswap Documentation
<div align="center">

This web application contains all documentation for Uniswap products. It is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
# 🦄 Uniswap Documentation

[![Made with Docusaurus](https://img.shields.io/badge/Made%20with-Docusaurus-blue.svg)](https://v2.docusaurus.io/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)

# Project Layout
Your comprehensive guide to all Uniswap products

### 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*
</div>

### Each item in a section should include the following:
- *Overview*
- *Guides*
- *Technical Reference*
---

## Adding Documentation
## 📚 Table of Contents

> **After deploying your change, please make sure you [update the search indices](#how-to-update-search-indices-with-algolia) if a new file was added as part of the change**
### Overview
A product overview should address points such as:
- [🏗️ Project Layout](#-project-layout)
- [📝 Contributing Documentation](#-contributing-documentation)
- [✅ Contribution Checklist](#-contribution-checklist)
- [🔧 Generating Technical References](#-generating-technical-references)
- [🔍 How to Update search indices with algolia](#how-to-update-search-indices-with-algolia)

- 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](./docs/contracts/v3/overview.md).
---

### 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
## 🏗️ Project Layout

By implementing these consistent principles Uniswap will have docs that are easy to understand and produce reusable code for its community.
The documentation is organized into four sections:

| Section | Description | Examples |
|---------|-------------|----------|
| 📘 **Concepts** | General Uniswap information | Liquidity, Fees |
| 📜 **Contracts** | Smart contract documentation | V3 Contracts, Permit2 |
| 🛠️ **SDKs** | Integration guides | v3-sdk, Swap Widget |
| 🔌 **APIs** | API documentation | Subgraph API |

> Each section includes:
> - ✨ Overview
> - 📋 Guides
> - 📚 Technical Reference

---

## 📝 Contributing Documentation

### Writing Overviews

A product overview should clearly address the following key points:

- **Main Components:** What are the high level components of the product?
- **Core Functionality:** What are the high level features and functions it provides?
- **Source Code Location:** Where can the product's source code be found?
- **Integration:** Where can the code artifact (e.g., npm) be accessed, and how can someone integrate it into their project?

For a good example, check out the [V3 Smart Contracts overview](./docs/contracts/v3/overview.md).

### Writing Guides

A guide is a reusable code example that illustrates a specific concept within the Uniswap ecosystem.

#### Structure of Guides

**1. Introduction:** Explain the concept of the piece of code and summarize what will be covered and the end result.

**2. Walkthrough:** Provide a step-by-step explanation of each line of code.

**3. Output:** Show the testable end results.

#### Key Principles of Guides

Each guide should:
- Be a standalone piece.
- Refer to a code example in our example repository.
- Use the least dependencies possible.
- Include input changes (e.g., address, tokens, amounts) in the code.

#### Best Practices for Guides

- Don't show unnecessary source code snippets. Instead, link to external source code or technical references.
- Keep all links and references at the bottom and reference them as footnotes to minimize distractions.
- Help the developer build something within **10 minutes** per guide, but provide references for deep dives.
- End a guide with a transition to the subsequent guide, recommendations, or real-world project examples.

By implementing these consistent principles and practices, Uniswap will have documentation that is easy to understand and produces reusable code for its community.

A good example is the [V3 SDK Guides](./docs/sdk/v3/guides/01-quick-start.md).

### Technical References
This should contain the technical reference for the exported interfaces. A good example is the [V3 SDK](./docs/sdk/v3/reference/overview).
These files can be created using the [guides below](#how-to-create-a-technical-reference).
### Writing Technical References

These should provide technical references for the exported interfaces. For a good example, see the [V3 SDK reference](./docs/sdk/v3/reference/overview). You can create these reference files by following the [guides](#generating-technical-references) below.

---

# ✅ Contribution Checklist

### Checklist for Product Documentation

Before submitting your product documentation, ensure you've addressed the following:

1. **Did I choose the correct section for the product?**
- Ensure the product is placed in the appropriate category.

2. **Did I create a folder for the product?**
- Ensure a dedicated folder exists for the product.

3. **Did I introduce any new concepts?**
- If yes, add them under: `/concepts/<category_name>/<product_name>`

4. **Did I include an overview of the product?**
- The overview should be located at: `<category_name>/<product_name>/overview`

5. **Did I include guides for the product?**
- Place them under: `<category_name>/<product_name>/guides`

6. **Did I include a technical reference for the product?**
- The technical reference should be located at: `<category_name>/<product_name>/reference`

# Contributing to Uniswap Docs
7. **Did I give each document a descriptive name or ID?**
- This is crucial for clarity and the document's URL.

## 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](./CONTRIBUTING.md).
8. **Did I submit a PR following the [contributing](./CONTRIBUTING.md) guidelines?**
- Ensure all steps in the contributing guide are followed.

## Checklist for adding a new product
9. **Did I update the search indices after my changes were deployed?**
- Be sure to follow the steps outlined in [how to update search indices](#how-to-update-search-indices-with-algolia).

- 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](./CONTRIBUTING.md) guidelines?
- Did I [update the search indices](#how-to-update-search-indices-with-algolia) after my change was deployed?
---

## Checklist example
### Example: Permit2 Smart Contract

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](./docs/contracts/)
- Did I create the product folder?
- In this case, [yes](./docs/contracts/permit2/)
- 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](./docs/contracts/permit2/overview.md)
- Did I include Guides of the product under *contracts/permit2/guides* ?
- No, they should be added [here](./docs/contracts/permit2/guides)
- Did I include Technical Reference of the product under *contracts/permit2/reference* ?
- Yes I added them [here](./docs/contracts/permit2/reference)
- Did I open a PR using the the [Contributing](./CONTRIBUTING.md) guidelines?
- Yes
- Did I update the search indices after my change was deployed?
- Yes I did using the [guides below](#how-to-update-search-indices-with-algolia)
To help clarify, let’s walk through the process for the *Permit2* smart contract:

# How to create a Technical Reference
## How to generate markdown files from solidity Natspec comments
1. **Correct section chosen?**
- Yes, under [contracts](./docs/contracts/).

Install solidity doc gen
`npm install solidity-docgen`
2. **Product folder created?**
- Yes, located at [contracts/permit2](./docs/contracts/permit2/).

Get the correct compiler version
`npm install -D solc-0.7@npm:[email protected]`
3. **Introduced new concepts?**
- No, no new concepts were added.

Put the updated template `contract.hbs` in a /templates folder under the same directory as /contracts that you want to generate
4. **Overview included?**
- Yes, it’s added [here](./docs/contracts/permit2/overview.md).

Run `npx solidity-docgen --solc-module solc-0.7 -t ./templates`
5. **Guides included?**
- No, but they should be added [here](./docs/contracts/permit2/guides).

# How to generate markdown files from typescript comments
6. **Technical reference included?**
- Yes, added [here](./docs/contracts/permit2/reference).

`npm install --save-dev typedoc typedoc-plugin-markdown`
7. **PR submitted using the contributing guidelines?**
- Yes, following the [Contributing](./CONTRIBUTING.md) guide.

Depending on how your project was created, you might have to install Typescript:
`npm install --save-dev typescript`
8. **Search indices updated after deployment?**
- Yes, following the [guides below](#how-to-update-search-indices-with-algolia).

`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.
# 🔧 Generating Technical References

# How to Update search indices with algolia
## From Solidity Natspec Comments

1. Install Solidity Docgen:
```bash
npm install solidity-docgen
```

2. Get the correct Solidity compiler version:
```bash
npm install -D solc-0.7@npm:[email protected]
```
3. Place the updated contract.hbs template in a /templates folder in the same directory as /contracts.

4. Run Docgen:
```bash
npx solidity-docgen --solc-module solc-0.7 -t ./templates
```

## From TypeScript Comments

1. Install Typedoc and Markdown Plugin:
```bash
npm install --save-dev typedoc typedoc-plugin-markdown
```

2. (Optional) Install TypeScript if needed:
```bash
npm install --save-dev typescript
```

3. Generate Documentation:
```bash
npx typedoc --out <docs> src/index.ts
```

> 💡 Use the --skipErrorChecking flag if necessary to handle types fetched during transpilation (e.g., contract ABIs).

**Note:** For more details, see [typedoc-plugin-markdown](https://www.npmjs.com/package/typedoc-plugin-markdown).



# 🔍 How to Update search indices with algolia

1. **Create an `.env` file** with the following variables:
- `APPLICATION_ID`
- `API_KEY` (with write access)
If you don't have these, please ask an Engineering Manager for assistance.

2. **Edit the `config.json` file** if necessary:
- Update the `start_url` with the new website URL.
- Set the `sitemap_url` with the updated website URL (e.g., for docs: `https://docs.uniswap.org/sitemap.xml`).
- Use `"v3-docs"` as the `index_name`.

3. **Install and start Docker Desktop:**
[Download Docker Desktop](https://www.docker.com/products/docker-desktop/)

4. **Install jq:**
```bash
brew install jq


5. Run the Docker container:
```bash
docker run -it --env-file=.env -e "CONFIG=$(cat ./config.json | jq -r tostring)" algolia/docsearch-scraper
```

- 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](https://www.docker.com/products/docker-desktop/) 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

Run the following command to install dependencies:

```console
yarn install
```

## Local Development
Start a local development server with:

```console
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.
This command starts a local development server and opens a browser window. Most changes are reflected live without needing to restart the server.

## Clear Cache

## Clear cache
To clear the cache, use:

```console
yarn docusaurus clear
```

## Build

Generate static content into the `build` directory with:

```console
yarn build
```

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

This content can be served using any static hosting service.

## Deployment
The application automatically deployed to production using [Vercel](https://vercel.com/uniswap/docs) upon merge into **main**.

The application is automatically deployed to production via [Vercel](https://vercel.com/uniswap/docs) upon merging into the **main** branch.

---

<div align="center">

### 🆘 Need Help?
[![Join our Discord](https://img.shields.io/badge/Join%20our%20Discord-7389D8?style=flat&logo=discord&logoColor=ffffff)](https://discord.com/invite/uniswap)
[![Twitter Follow](https://img.shields.io/twitter/follow/Uniswap?style=social)](https://twitter.com/Uniswap)

</div>