{"id":18263720,"url":"https://github.com/yearn/yearn-devdocs","last_synced_at":"2025-04-04T16:15:25.709Z","repository":{"id":37077156,"uuid":"361689122","full_name":"yearn/yearn-devdocs","owner":"yearn","description":"yearn documentation","archived":false,"fork":false,"pushed_at":"2024-10-29T21:30:12.000Z","size":90385,"stargazers_count":79,"open_issues_count":9,"forks_count":70,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-10-29T23:44:58.636Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.yearn.fi","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yearn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-26T09:19:17.000Z","updated_at":"2024-10-29T21:27:31.000Z","dependencies_parsed_at":"2023-02-15T13:01:34.065Z","dependency_job_id":"4cb183ae-bbf4-43e4-9a2a-beb6c3a87224","html_url":"https://github.com/yearn/yearn-devdocs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yearn%2Fyearn-devdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yearn%2Fyearn-devdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yearn%2Fyearn-devdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yearn%2Fyearn-devdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yearn","download_url":"https://codeload.github.com/yearn/yearn-devdocs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247208161,"owners_count":20901570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T11:12:25.053Z","updated_at":"2025-04-04T16:15:25.690Z","avatar_url":"https://github.com/yearn.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Yearn Protocol Documentation Website\n\nThe Yearn Docs [website](https://docs.yearn.fi/) is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.\n\n## Installation and Setup\n\n1. Fork the yearn-devdocs repository at https://github.com/yearn/yearn-devdocs\n\n2. clone your forked repo locally. Replace `\u003cyourUserName\u003e` with your github user name\n\n    ```bash\n    git clone https://github.com/\u003cyourUserName\u003e/yearn-devdocs\n    cd yearn-devdocs\n    ```\n\n### Install project dependencies\n\n1. Install Node dependencies\n\n    make sure you have the most recent lts node version installed. NVM is Node Version Manager and you may need to install this if you don't have it.\n\n    ```bash\n    nvm install --lts\n    ```\n\n    ```bash\n    nvm use --lts\n\n    ```\n\n    Then install node dependencies\n\n    ```bash\n    yarn\n    ```\n\n2. Install Python/Vyper dependencies for natspec docs generation (You can skip this step if you aren't working on smart contract documentation)\n\n    This assumes you are using linux and will use the apt package manager. If not, other OSes have their own package manager that will have Python and Vyper.\n\n    2a. update the apt package manager\n\n    ```bash\n    sudo apt update\n    ```\n\n    2b. Install Python 3\n\n    ```bash\n    sudo apt install python3\n    ```\n\n    2c. Verify the installation\n\n    ```bash\n    python3 --version\n    ```\n\n    2d. Create and initialize python virtual environment\n\n    ```bash\n    python3 -m venv venv\n    source venv/bin/activate\n    ```\n\n    2e. install requirements\n\n    ```bash\n    python3 -m pip install -r requirements.txt\n    ```\n\n    2f. Install Foundry\n\n    ``` bash\n    curl -L https://foundry.paradigm.xyz | bash\n    ```\n\n    open a new terminal window and run\n\n    ```bash\n    foundryup\n    ```\n\n## Local Development\n\nThis command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.\n\n```bash\nyarn start\n```\n\nRunning `yarn start` will also run a script that checks the validity of smart contract addresses in the docs against a local constants file. This runs on every dev run as a way to keep the checks updated and the information about them on the site current (all PRs will include an update to last check time). If you want to run `yarn start` without the `runAddressChecks` script running you can run `yarn start-no-check`.\n\n## Build\n\nThis command generates static content into the `build` directory and can be served using any static content hosting service.\n\n```bash\nyarn build\n```\n\n## Configure .env\n\nThe docs site pulls data from on-chain smart contracts, so an API key is necessary. The default is an Alchemy API key so the easiest thing to do is get a free api key from them at https://www.alchemy.com/pricing.\n\nRename the `.env.example` file in the root directory to `.env` and add your API key where it says \"yourApiKeyHere\" without any quotes or backticks.\n\nIf you would like to use a different RPC service, or your own node to pull blockchain data, you can edit the publicClient in `/src/context/PublicClientContext`.\n\n## Deployment\n\nGenerally you should not need to use this as there is a github actions script that builds and deploys the site when a pull request is merged to the `master` branch of the upstream Yearn Github Repo.\n\nIf you are using GitHub pages for hosting, this command is a convenient way to build the website and push it to the `gh-pages` branch.\n\n```bash\nGIT_USER=\u003cYour GitHub username\u003e USE_SSH=true yarn deploy\n```\n\n---\n\n## Contribute\n\nFor detailed information on the contributing workflow, please see the [Contributing Documentation](CONTRIBUTING.md).\n\n### Documentation Structure\n\nWe have 2 types of documentation: General documentation and Natspec documentation of smart contracts:\n\n- General documentation is generated from markdown or HTML files and edited manually.\n- Natspec documentation is automatically generated from another repository's code.\n\n#### General Documentation\n\nThis documentation is located in the `docs` folder and most content is either in the `getting-started` folder (User Docs), the `developers` folder (Dev Docs), or the `contributing` folder (DAO Docs).\n\n#### Natspec Documentation\n\n⚠️ As of mid 2024, versioning has been changed!\n\nBecause Yearn supports multiple products with their own version numbers, versioning is now done manually using folder structure (instead of native Docusaurus versioning) to keep things organized. There are folders for all versions of the smart contract [NatSpec](https://docs.soliditylang.org/en/latest/natspec-format.html) documentation in:\n\n```plaintext\ndocs/developers/smart-contracts\n├── V3\n│   ├── Current contract 1\n│   ├── Current contract 2\n│   └── Current contract n...\n│\n├── V2\n│   ├── Current contract 1\n│   ├── Current contract 2\n│   └── Current contract n...\n│\n├── Deprecated   \n│   ├── V3 Deprecated\n│   │   ├── v3.x.x\n│   │   │   ├── contract 1\n│   │   │   ├── contract 2\n│   │   │   └── contract n...\n│   │   └── v3.x.x\n│   │       ├── contract 1\n│   │       ├── contract 2\n│   │       └── contract n...\n│   │\n│   └── V2 Deprecated\n│       ├── v0.4.x\n│       │   ├── contract 1\n│       │   ├── contract 2\n│       │   └── contract n...\n│       └── v0.4.x\n│           ├── contract 1\n│           ├── contract 2\n│           └── contract n...\n```\n\n### Generating V2 Versioned Documentation\n\n#### Dependencies\n\n- Clone the V2 vaults repository: [yearn/yearn-vaults](https://github.com/yearn/yearn-vaults) in the same folder where you cloned yearn-devdocs (not inside devdocs, but beside it)\n- Run the yearn-vaults [installation](https://github.com/yearn/yearn-vaults#installation), you will need to have brownie installed to run it once so it installs the required dependencies.\n- Check the vyper compiler version on the vaults repo ([here](https://github.com/yearn/yearn-vaults/blob/master/contracts/Vault.vy#L1)) and update the vyper version in the `requirements.txt` file in this repo.\n- Make sure [Vault.vy](https://github.com/yearn/yearn-vaults/blob/master/contracts/Vault.vy#L1) and [Registry.vy](https://github.com/yearn/yearn-vaults/blob/master/contracts/Registry.vy#L1) on `yearn-vaults` folder has the same compiler version on their first line. If not, bump the file with the lowest version to the current version the other uses.\n- If any contract file in yearn-vaults uses a fixed compiler version (without leading `^`) you may have to add it so the `solc` compiler will run. Also, make sure `solc` version is up-to-date.\n- If you get errors with global `solc` try to install it locally on the project with npm\n\n#### Generate\n\nTo generate API documentation and coin a new release, do the following.\n\n1. Create new folder in `docs/developers/smart-contracts/deprecated/V2` with the current version number (i.e. version-0.4.6)\n2. Move existing docs into newly created folder. Leave the index.md file and update the vault version called out in it to the new version number.\n3. Generate docs from contracts using vydoc or similar documentation creator.\n4. lint and clean up docs\n5. Move new generated docs into `docs/developers/smart-contracts/v2/`\n\n#### VyDoc\n\nGenerate docs with vydoc. Arguments are:\n-i is where the smart contracts live\n-o is where the generated documentation will be written\n-t is the template used to generate the docs\n-c is the compiler (make sure you have the correct vyper installed)\n\n```bash\nnpx vydoc -i ../yearn-vaults/contracts/ -o ./natspec/temp -t ./natspec/contract.ejs -c $(which vyper)\n```\n\n```bash\nnpx solidity-docgen@0.5.17 --solc-module solc --templates=natspec --helpers=helpers/solidityHelpers.js -i ../yearn-vaults/contracts/ -o ./docs/developers/smart-contracts/v2\n```\n\n### Generating V3 Smart Contract Documentation\n\n1. All necessary V3 github repos should be included as git submodules within this repo. They are located in the `natspec/lib` folder. If the repo folders are empty, you need to install the submodules:\n\n```bash\ngit submodule update --init --recursive\n```\n\nFor reference, these are the addresses for the different submodules:\n\n- [yearn/yearn-vaults-v3](https://github.com/yearn/yearn-vaults-v3/tree/master)\n- [yearn/vault-periphery](https://github.com/yearn/vault-periphery)\n- [yearn/tokenized-strategy](https://github.com/yearn/tokenized-strategy/tree/master)\n- [yearn/tokenized-strategy-periphery](https://github.com/yearn/tokenized-strategy-periphery/tree/master)\n- [yearn/yearn-ERC4626-Router](https://github.com/yearn/Yearn-ERC4626-Router)\n  \n2. If you haven't already, create a python virtual environment and initialize.\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n3. If you haven't already, install the python requirements.\n\n```bash\npython3 -m pip install -r requirements.txt\n```\n\n4. If you haven't already, install Forge.\n\n``` bash\ncurl -L https://foundry.paradigm.xyz | bash\n```\n\nopen a new terminal window and run\n\n```bash\nfoundryup\n```\n\nthen re-activate your venv\n\n```bash\nsource venv/bin/activate\n```\n\nYou should now be ready to generate some docs! To generate new documentation run the v3 documentation script.\n\n```bash\nyarn v3-docs\n```\n\nThis should generate a prompt for you to follow:\n\n- If you are creating docs for a new release then select \"new\" and enter the new version number. This will then:\n  - Generate documentation for the contracts listed in the `v3-contracts` object in `smartContracts.json`.\n  - Move the existing \"current\" files into a new folder in `developers/smart-contracts/deprecated/V3` with the old version number.\n  - Add the new files to `developers/smart-contracts/v3`\n  - update the index.md file to reflect the new release version.\n- If you only want to update without creating a new version, or update a few files or a certain folder, you can use the \"update\" option in the prompt.\n  - Then select whether you want to update all v3 files or only selected ones.\n    - If you select \"files\", the script will then read from the `selectedFiles` array in the `natspec-generate.mjs` script file. Edit that array to include the file names you want. (Naming should match existing files e.g. `TokenizedStrategy`).\n    - If you select \"folder\" then the script will read the path in the `folderToUpdate` variable. Be aware this will include all sub-folders as well.\n  - After selecting options, everything else runs the same as selecting \"new\" but without copying your existing files to the deprecated folder.\n\nThe script runs a markdown linter as well as some regex to remove elements that break MDX and some broken links, so the output files should be pretty clean, but they still may need some manual adjustment. You may also still get build errors if there are characters in the natspec that MDX v3 doesn't like (like {} and \u003c\u003e). These will need to be removed manually or escaped out of using the `\\` character. More info [here](https://docusaurus.io/docs/markdown-features/react#markdown-and-jsx-interoperability). Steps to fix these types of errors:\n\nThere will also probably be some broken links. These are usually from the forge doc build and will reference the structure of the forge doc output. Easiest way to find these is to do a search in VSCode. I search for `(/src/` with `developers/smart-contracts/v3/*` included and `developers/smart-contracts/v3/deprecated/*` excluded. The most common broken links will be links generated in Forge that link to other sections in the same file. These use the hash router and usually just need everything before the hash to be removed to work. i.e. `[redeem](/src/Yearn4626Router.sol/contract.Yearn4626Router.md#migrate)` -\u003e `[redeem](#migrate)`.\n\n---\n\n### Custom Elements\n\n#### Detail Element\n\nThis is a Detail element that contains other text inside. If you format the summary section as shown it renders markdown correctly.\n\n```markdown\n\u003cdetails className=\"customDetails\"\u003e\n\n  \u003csummary\u003e\n  \n  ## Title Here\n  \n  \u003c/summary\u003e\n\n### Subtitles as needed\n\ncontent here\n\n\u003c/details\u003e\n```\n\nThere is also a \"customFaqDetails\" css class that removes the borders.\n\n#### PrettyLink\n\nThe PrettyLink element makes your links into button-like elements with subtle animation and yearn styling. These links will fill the full width of the markdown document. Can be used with naked links or with markdown style links.\n\n```markdown\n\u003cPrettyLink\u003e[your link name](your-link-url)\u003c/PrettyLink\u003e\n```\n\n#### Yearn Admonition\n\nThere are custom informational Yearn-styled admonitions that can be used like any other admonition.\n\n```markdown\n:::yearn[title-goes-here]\n\ntext content\n\n:::\n```\n\n```markdown\n:::yearn-data[title-goes-here]\n\ntext content\n\n:::\n```\n\nIf you create a new docs plugin in `docusaurus.config` you will need to initialize this admonition in that plugin instance like this:\n\n```js\n\n plugins: [\n    [\n      '@docusaurus/plugin-content-docs',\n      {\n        id: 'new docs section',\n        //other vars\n        admonitions: {\n          keywords: ['yearn', 'yearn-data'],\n          extendDefaults: true,\n        },\n      },\n    ],\n]\n\n```\n\n### Blockchain RPC Calls\n\nYou can make RPC calls to read contract data from on-chain sources and display them within the docs. This is done using the Viem ethereum library. But if all you are doing is writing docs, you don't need to worry about the details here. You can add the information for all the read calls you want within the front-matter of a markdown document. [Front-matter](https://docusaurus.io/docs/markdown-features#front-matter) is metadata that docusaurus reads when serving pages.\n\nTo make a blockchain call you need to structure your data in the following format:\n\n```yml\n---\nrpcCalls:\n\n  - name: 'dYFI Redemption' \u003c-- descriptive name of contract to be called for use in component\n    chain: '1' \u003c--chainID\n    address: '0x7dC3A74F0684fc026f9163C6D5c3C99fda2cf60a' \u003c--the contract address\n    abiName: 'dyfiRedemptionABI' \u003c--name of exported ABI object from src/ethereum/ABIs\n    methods:  \n      - 'discount' \u003c-- name of call (if no arguments needed)\n      - 'get_latest_price'\n      - name: 'eth_required' \u003c-- name of call (if arguments are needed)\n        args: ['1000000000000000000'] \u003c--comma separated arguments of call as an array (square brackets)\n\n  - name: 'YFI token'\n    chain: '1'\n    address: '0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e'\n    abiName: 'yfiTokenABI'\n    methods:\n      - totalSupply\n      - symbol\n---\n```\n\n- Each element in rpcCalls creates an object that is exported from the front-matter.\n- Each object can contain calls to different functions in the same contract if you add them into the methods field.\n  - If the method doesn't require args (the function doesn't require any input) then you only need to list the name. This is the name you see on etherscan, without the number.\n  - If the method does require an argument then you need to add it with a name parameter and an args parameter, with the values for the arguments separated by commas and in square brackets.\n\n![name on etherscan](static/img/guides/readme/etherscan1.png)\n\n![name and args on etherscan](static/img/guides/readme/etherscan2.png)\n\n⚠️ When adding a new contract to call, you need to add the ABI to \"src/ethereum/ABIs\". Create a new typescript file with the name of your ABI. The convention is to name it in camelCase and end it with ABI (i.e. yfiTokenABI.ts). Then paste the ABI into the file (you can copy it from etherscan. It is in the contract-\u003ecode section.). You need to export it and add `as const` at the end.\n\n```js\n// src/ethereum/ABIs/yourContractABI.ts\nexport const yourContractABI = [\n    {\n    // abi data here\n    }\n] as const\n\n```\n\nYou then need to export this element from the index.ts file in the same directory. Add a line exporting your ABI as shown below.\n\n```js\nexport * from './yourContractABI'\n```\n\nTo display the data from the calls, use the \\\u003cContractData\u003e component. It takes the following arguments:\n\n- `contractName` which reads the name field in the rpcCall defined in the front-matter\n- `methodName` which reads from the methods in the rpcCall defined in the front-matter\n- `decimals` which is an optional argument to format your output to display with human readable decimals. It should be wrapped in curly brackets \\{\\}.\n\n```markdown\nThe current redemption discount is: \u003cContractData contractName='dYFI Redemption' methodName='discount' decimals={18} /\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyearn%2Fyearn-devdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyearn%2Fyearn-devdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyearn%2Fyearn-devdocs/lists"}