From 747de4be45b80055a4e1cae3e06cf476843b0d40 Mon Sep 17 00:00:00 2001 From: "Michele \"Ubik\" De Simoni" Date: Wed, 26 Aug 2020 21:59:30 +0200 Subject: [PATCH] Restructure docs generation around mkdocs --- .gitignore | 1 + CONTRIBUTING.md | 67 +++++++ README.md | 3 + ...VotingTokensForStableCoinFunctionality.sol | 3 +- .../stableCoin/standalone/IDoubleProxy.sol | 6 + .../standalone/IMWDFunctionalitiesManager.sol | 6 + contracts/stableCoin/standalone/IMWDProxy.sol | 17 ++ .../stableCoin/standalone/IStableCoin.sol | 182 +----------------- .../stableCoin/standalone/IStateHolder.sol | 8 + .../stableCoin/standalone/IUniswapV2Pair.sol | 32 +++ .../standalone/IUniswapV2Router.sol | 101 ++++++++++ .../stableCoin/standalone/StableCoin.sol | 10 +- docs/Makefile | 20 -- docs/docs.json | 132 ------------- docs/make.bat | 35 ---- docs/mkdocs.yml | 29 +++ docs/requirements.in | 4 +- docs/requirements.txt | 44 ++--- docs/solidity-docgen-templates/contract.hbs | 53 +++++ docs/source/api.rst | 16 -- docs/source/conf.py | 90 --------- docs/source/index.rst | 21 -- package.json | 7 + 23 files changed, 361 insertions(+), 526 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 README.md create mode 100644 contracts/stableCoin/standalone/IDoubleProxy.sol create mode 100644 contracts/stableCoin/standalone/IMWDFunctionalitiesManager.sol create mode 100644 contracts/stableCoin/standalone/IMWDProxy.sol create mode 100644 contracts/stableCoin/standalone/IStateHolder.sol create mode 100644 contracts/stableCoin/standalone/IUniswapV2Pair.sol create mode 100644 contracts/stableCoin/standalone/IUniswapV2Router.sol delete mode 100644 docs/Makefile delete mode 100644 docs/docs.json delete mode 100644 docs/make.bat create mode 100644 docs/mkdocs.yml create mode 100644 docs/solidity-docgen-templates/contract.hbs delete mode 100644 docs/source/api.rst delete mode 100644 docs/source/conf.py delete mode 100644 docs/source/index.rst diff --git a/.gitignore b/.gitignore index 0177b03..af8ddd5 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ /**/spa/**/style.css docs/build +docs/md-build # Created by https://www.toptal.com/developers/gitignore/api/python,solidity,visualstudiocode,react # Edit at https://www.toptal.com/developers/gitignore?templates=python,solidity,visualstudiocode,react diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..55ee2fc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,67 @@ +# Contributing guidelines + +## Table of Contents + +- [Table of Contents](#table-of-contents) +- [Coding Style](#coding-style) + - [Solidity](#solidity) + - [JavaScript](#javascript) + - [Python](#python) +- [Documentation](#documentation) + - [mkdocs](#mkdocs) + +## Coding Style + +### Solidity + +* Solidity portions of the codebase adhere follow the official [Solidity Styleguide] + +### JavaScript + +### Python + +* Python portions of the codebase follow standard PEP8 best practices. +* Python code must be formatted using the Black formatter using the provided settings. + +## Documentation + +New addition to the codebase must be fully documented. + +- JavaScript portions of the code should be annotated using JSDoc style docstrings. +- Solidity portions of the code should be fully annotated using [NatSpec] and [Solidity Domain for Sphinx]. + +Documentation is generated using [solidity-docgen] and rendered via [mkdocs]. +[solidity-docgen] parses NatSpec and outputs `.md` files inside `docs/md-build` according +to an Handlebars template located at `docs/solidity-docgen-templates/contract.hbs`. + +**NOTE:** Each `.sol` file should contain only one `Interface` or `Contract`. + +To build the documentation: + +```console +yarn build docs +``` + +To serve the documentation + +```console +yarn build docs:serve +``` + +### mkdocs + +To install [mkdocs] Python must be installed in the system. + +``` +pip install docs/requirements.in +``` + +**NOTE:** Working inside a virtual environment is highly recommended! + +--- + +[Solidity Styleguide]: https://solidity.readthedocs.io/en/v0.7.0/style-guide.html +[NatSpec]: https://solidity.readthedocs.io/en/v0.7.0/style-guide.html#natspec +[Write the Docs!]: docs/source/write_the_docs.rst +[solidity-docgen]: https://github.com/OpenZeppelin/solidity-docgen +[mkdocs]: https://www.mkdocs.org/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..cd811d5 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# unifi + +A DFO protocol powered DeFi set of tools built on top of Uniswap. diff --git a/contracts/stableCoin/MintNewVotingTokensForStableCoinFunctionality.sol b/contracts/stableCoin/MintNewVotingTokensForStableCoinFunctionality.sol index 6e0c552..d19cef6 100644 --- a/contracts/stableCoin/MintNewVotingTokensForStableCoinFunctionality.sol +++ b/contracts/stableCoin/MintNewVotingTokensForStableCoinFunctionality.sol @@ -3,7 +3,8 @@ pragma solidity ^0.6.0; /** - * @title Mint Voting Tokens (unifi) by burning Stable Coin (uSD) // DOCUMENT + * @title Mint Voting Tokens ($unifi) by burning Stable Coin ($uSD) // DOCUMENT + * @dev This contract define the logic that is used */ contract MintNewVotingTokensForStableCoinFunctionality { function onStart(address, address) public { diff --git a/contracts/stableCoin/standalone/IDoubleProxy.sol b/contracts/stableCoin/standalone/IDoubleProxy.sol new file mode 100644 index 0000000..5b6c101 --- /dev/null +++ b/contracts/stableCoin/standalone/IDoubleProxy.sol @@ -0,0 +1,6 @@ +pragma solidity ^0.6.0; + +// DOCUMENT +interface IDoubleProxy { + function proxy() external view returns (address); +} diff --git a/contracts/stableCoin/standalone/IMWDFunctionalitiesManager.sol b/contracts/stableCoin/standalone/IMWDFunctionalitiesManager.sol new file mode 100644 index 0000000..a99e8f2 --- /dev/null +++ b/contracts/stableCoin/standalone/IMWDFunctionalitiesManager.sol @@ -0,0 +1,6 @@ +pragma solidity ^0.6.0; + +// DOCUMENT +interface IMVDFunctionalitiesManager { + function isAuthorizedFunctionality(address functionality) external view returns (bool); +} diff --git a/contracts/stableCoin/standalone/IMWDProxy.sol b/contracts/stableCoin/standalone/IMWDProxy.sol new file mode 100644 index 0000000..b4c6d23 --- /dev/null +++ b/contracts/stableCoin/standalone/IMWDProxy.sol @@ -0,0 +1,17 @@ +pragma solidity ^0.6.0; + +// DOCUMENT +interface IMVDProxy { + function getToken() external view returns (address); + + function getMVDFunctionalitiesManagerAddress() external view returns (address); + + function getMVDWalletAddress() external view returns (address); + + function getStateHolderAddress() external view returns (address); + + function submit(string calldata codeName, bytes calldata data) + external + payable + returns (bytes memory returnData); +} diff --git a/contracts/stableCoin/standalone/IStableCoin.sol b/contracts/stableCoin/standalone/IStableCoin.sol index a1b352a..7569796 100644 --- a/contracts/stableCoin/standalone/IStableCoin.sol +++ b/contracts/stableCoin/standalone/IStableCoin.sol @@ -156,7 +156,7 @@ interface IStableCoin { ) external returns (uint256 amountA, uint256 amountB); /** - * @dev Rebalance by Credit is triggered when the total amount of source tokens is greater + * @dev Rebalance by Credit is triggered when the total amount of source tokens' value is greater * than uSD circulating supply. Rebalancing is done by withdrawing the excess from the pool. * * ===== @@ -172,183 +172,13 @@ interface IStableCoin { ) external returns (uint256 redeemed); /** - * @dev // DOCUMENT - */ - function rebalanceByDebt(uint256 amount) external returns (uint256); -} - -// -----------------------------------------------------------------------------------------------| - -// DOCUMENT -interface IDoubleProxy { - function proxy() external view returns (address); -} - -// -----------------------------------------------------------------------------------------------| - -// DOCUMENT -interface IMVDProxy { - function getToken() external view returns (address); - - function getMVDFunctionalitiesManagerAddress() external view returns (address); - - function getMVDWalletAddress() external view returns (address); - - function getStateHolderAddress() external view returns (address); - - function submit(string calldata codeName, bytes calldata data) - external - payable - returns (bytes memory returnData); -} - -// -----------------------------------------------------------------------------------------------| - -// DOCUMENT -interface IMVDFunctionalitiesManager { - function isAuthorizedFunctionality(address functionality) external view returns (bool); -} - -// -----------------------------------------------------------------------------------------------| - -// DOCUMENT -interface IStateHolder { - function getBool(string calldata varName) external view returns (bool); - - function getUint256(string calldata varName) external view returns (uint256); -} - -// -----------------------------------------------------------------------------------------------| - -/** - * @title Uniswap V2 Router - * @dev Route liquidity back and forth an Uniswap Liquidity Pool. - * For more information see: https://uniswap.org/docs/v2/smart-contracts/router02/ - * - */ -interface IUniswapV2Router { - /** - * https://uniswap.org/docs/v2/smart-contracts/library#getamountsout - * Given an input asset amount and an array of token addresses, calculates all subsequent maximum - * output token amounts by calling getReserves for each pair of token addresses in the path in - * turn, and using these to call getAmountOut. Useful for calculating optimal token amounts - * before calling swap. - */ - function getAmountsOut(uint256 amountIn, address[] calldata path) - external - view - returns (uint256[] memory amounts); - - /** - * @dev Removes liquidity from an ERC-20⇄ERC-20 pool - * - * https://uniswap.org/docs/v2/smart-contracts/router02/#addliquidity - * - * ===== - * - * @param tokenA A pool token - * @param tokenB A pool token - * @param liquidity The amount of liquidity tokens to remove - * @param amountAMin The minimum amount of tokenA that must be received for the transaction not to revert - * @param amountBMin The minimum amount of tokenB that must be received for the transaction not to revert - * @param to Recipient of the underlying assets - * @param deadline Unix timestamp after which the transaction will revert - * - * ===== - * - * @return amountA The amount of tokenA received - * @return amountB The amount of tokenB received - * - */ - function removeLiquidity( - address tokenA, - address tokenB, - uint256 liquidity, - uint256 amountAMin, - uint256 amountBMin, - address to, - uint256 deadline - ) external returns (uint256 amountA, uint256 amountB); - - /** - * @dev Add Liquidity to an ERC-20⇄ERC-20 pool - * - * - To cover all possible scenarios, msg.sender should have already given the router an allowance - * of at least amountADesired/amountBDesired on tokenA/tokenB. - * - Always adds assets at the ideal ratio, according to the price when the transaction is executed. - * - If a pool for the passed tokens does not exists, one is created automatically, and exactly - * amountADesired/amountBDesired tokens are added. - * - * https://uniswap.org/docs/v2/smart-contracts/router02/#addliquidity - * - * ===== - * - * @param tokenA A pool token - * @param tokenB A pool token - * @param liquidity The amount of liquidity tokens to remove - * @param amountADesired The amount of tokenA to add as liquidity if the B/A price is <= - * amountBDesired/amountADesired (A depreciates). - * @param amountBDesired The amount of tokenB to add as liquidity if the A/B price is <= - * amountADesired/amountBDesired (B depreciates). - * @param amountAMin Bounds the extent to which the B/A price can go up before the transaction reverts. Must be <= amountADesired. - * @param amountBMin Bounds the extent to which the A/B price can go up before the transaction reverts. Must be <= amountBDesired. - * @param to Recipient of the underlying assets - * @param deadline Unix timestamp after which the transaction will revert + * @dev Rebalance by Credit is triggered when the total amount of source tokens' value is greater + * than uSD circulating supply. Rebalancing is done by withdrawing the excess from the pool. * * ===== * - * @return amountA The amount of tokenA sent to the pool - * @return amountB The amount of tokenB sent to the pool - * @return liquidity The amount of liquidity tokens minted - * + * @notice Positive imbalances can be caused by the accrual of liquidity provider fee. Withdrawn tokens + * are stored inside the Unifi DFO as a source of long-term value */ - function addLiquidity( - address tokenA, - address tokenB, - uint256 amountADesired, - uint256 amountBDesired, - uint256 amountAMin, - uint256 amountBMin, - address to, - uint256 deadline - ) - external - returns ( - uint256 amountA, - uint256 amountB, - uint256 liquidity - ); -} - -// -----------------------------------------------------------------------------------------------| - -// DOCUMENT -/** - * @title Uniswap V2 Pair - */ -interface IUniswapV2Pair { - // DOCUMENT - function decimals() external pure returns (uint8); - - // DOCUMENT - function totalSupply() external view returns (uint256); - - // DOCUMENT - function token0() external view returns (address); - - // DOCUMENT - function token1() external view returns (address); - - // DOCUMENT - function balanceOf(address account) external view returns (uint256); - - // DOCUMENT - function getReserves() - external - view - returns ( - uint112 reserve0, - uint112 reserve1, - uint32 blockTimestampLast - ); + function rebalanceByDebt(uint256 amount) external returns (uint256); } diff --git a/contracts/stableCoin/standalone/IStateHolder.sol b/contracts/stableCoin/standalone/IStateHolder.sol new file mode 100644 index 0000000..9a23fb8 --- /dev/null +++ b/contracts/stableCoin/standalone/IStateHolder.sol @@ -0,0 +1,8 @@ +pragma solidity ^0.6.0; + +// DOCUMENT +interface IStateHolder { + function getBool(string calldata varName) external view returns (bool); + + function getUint256(string calldata varName) external view returns (uint256); +} diff --git a/contracts/stableCoin/standalone/IUniswapV2Pair.sol b/contracts/stableCoin/standalone/IUniswapV2Pair.sol new file mode 100644 index 0000000..7658298 --- /dev/null +++ b/contracts/stableCoin/standalone/IUniswapV2Pair.sol @@ -0,0 +1,32 @@ +pragma solidity ^0.6.0; + +// DOCUMENT +/** + * @title Uniswap V2 Pair + */ +interface IUniswapV2Pair { + // DOCUMENT + function decimals() external pure returns (uint8); + + // DOCUMENT + function totalSupply() external view returns (uint256); + + // DOCUMENT + function token0() external view returns (address); + + // DOCUMENT + function token1() external view returns (address); + + // DOCUMENT + function balanceOf(address account) external view returns (uint256); + + // DOCUMENT + function getReserves() + external + view + returns ( + uint112 reserve0, + uint112 reserve1, + uint32 blockTimestampLast + ); +} diff --git a/contracts/stableCoin/standalone/IUniswapV2Router.sol b/contracts/stableCoin/standalone/IUniswapV2Router.sol new file mode 100644 index 0000000..eb3849b --- /dev/null +++ b/contracts/stableCoin/standalone/IUniswapV2Router.sol @@ -0,0 +1,101 @@ +pragma solidity ^0.6.0; + +/** + * @title Uniswap V2 Router + * @dev Route liquidity back and forth an Uniswap Liquidity Pool. + * For more information see: https://uniswap.org/docs/v2/smart-contracts/router02/ + * + */ +interface IUniswapV2Router { + /** + * https://uniswap.org/docs/v2/smart-contracts/library#getamountsout + * Given an input asset amount and an array of token addresses, calculates all subsequent maximum + * output token amounts by calling getReserves for each pair of token addresses in the path in + * turn, and using these to call getAmountOut. Useful for calculating optimal token amounts + * before calling swap. + */ + function getAmountsOut(uint256 amountIn, address[] calldata path) + external + view + returns (uint256[] memory amounts); + + /** + * @dev Removes liquidity from an ERC-20⇄ERC-20 pool + * + * https://uniswap.org/docs/v2/smart-contracts/router02/#addliquidity + * + * ===== + * + * @param tokenA A pool token + * @param tokenB A pool token + * @param liquidity The amount of liquidity tokens to remove + * @param amountAMin The minimum amount of tokenA that must be received for the transaction not to revert + * @param amountBMin The minimum amount of tokenB that must be received for the transaction not to revert + * @param to Recipient of the underlying assets + * @param deadline Unix timestamp after which the transaction will revert + * + * ===== + * + * @return amountA The amount of tokenA received + * @return amountB The amount of tokenB received + * + */ + function removeLiquidity( + address tokenA, + address tokenB, + uint256 liquidity, + uint256 amountAMin, + uint256 amountBMin, + address to, + uint256 deadline + ) external returns (uint256 amountA, uint256 amountB); + + /** + * @dev Add Liquidity to an ERC-20⇄ERC-20 pool + * + * - To cover all possible scenarios, msg.sender should have already given the router an allowance + * of at least amountADesired/amountBDesired on tokenA/tokenB. + * - Always adds assets at the ideal ratio, according to the price when the transaction is executed. + * - If a pool for the passed tokens does not exists, one is created automatically, and exactly + * amountADesired/amountBDesired tokens are added. + * + * https://uniswap.org/docs/v2/smart-contracts/router02/#addliquidity + * + * ===== + * + * @param tokenA A pool token + * @param tokenB A pool token + * @param liquidity The amount of liquidity tokens to remove + * @param amountADesired The amount of tokenA to add as liquidity if the B/A price is <= + * amountBDesired/amountADesired (A depreciates). + * @param amountBDesired The amount of tokenB to add as liquidity if the A/B price is <= + * amountADesired/amountBDesired (B depreciates). + * @param amountAMin Bounds the extent to which the B/A price can go up before the transaction reverts. Must be <= amountADesired. + * @param amountBMin Bounds the extent to which the A/B price can go up before the transaction reverts. Must be <= amountBDesired. + * @param to Recipient of the underlying assets + * @param deadline Unix timestamp after which the transaction will revert + * + * ===== + * + * @return amountA The amount of tokenA sent to the pool + * @return amountB The amount of tokenB sent to the pool + * @return liquidity The amount of liquidity tokens minted + * + */ + function addLiquidity( + address tokenA, + address tokenB, + uint256 amountADesired, + uint256 amountBDesired, + uint256 amountAMin, + uint256 amountBMin, + address to, + uint256 deadline + ) + external + returns ( + uint256 amountA, + uint256 amountB, + uint256 liquidity + ); +} diff --git a/contracts/stableCoin/standalone/StableCoin.sol b/contracts/stableCoin/standalone/StableCoin.sol index 2d45bf6..6c84858 100644 --- a/contracts/stableCoin/standalone/StableCoin.sol +++ b/contracts/stableCoin/standalone/StableCoin.sol @@ -4,11 +4,17 @@ pragma solidity ^0.6.0; import "./ERC20.sol"; import "./IStableCoin.sol"; +import "./IMWDFunctionalitiesManager.sol"; +import "./IMWDProxy.sol"; +import "./IDoubleProxy.sol"; +import "./IStateHolder.sol"; +import "./IUniswapV2Pair.sol"; +import "./IUniswapV2Router.sol"; /** * @title StableCoin - * @dev Contract for the "uSD" Stable Coin. It's an ERC20 token extended with the IStableCoin - * interface. + * @dev Contract for the "uSD" Stable Coin. + * It's an ERC20 token extended with the IStableCoin interface and DFO protocol magic. */ contract StableCoin is ERC20, IStableCoin { // |------------------------------------------------------------------------------------------| diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/docs.json b/docs/docs.json deleted file mode 100644 index b63e6ac..0000000 --- a/docs/docs.json +++ /dev/null @@ -1,132 +0,0 @@ - -======= ../contracts/stableCoin/standalone/IStableCoin.sol:IDoubleProxy ======= -Developer Documentation -{ - "kind": "dev", - "methods": {}, - "version": 1 -} - -======= ../contracts/stableCoin/standalone/IStableCoin.sol:IMVDFunctionalitiesManager ======= -Developer Documentation -{ - "kind": "dev", - "methods": {}, - "version": 1 -} - -======= ../contracts/stableCoin/standalone/IStableCoin.sol:IMVDProxy ======= -Developer Documentation -{ - "kind": "dev", - "methods": {}, - "version": 1 -} - -======= ../contracts/stableCoin/standalone/IStableCoin.sol:IStableCoin ======= -Developer Documentation -{ - "details": "Define the interface for the usD", - "kind": "dev", - "methods": - { - "allowedPairs()": - { - "details": "Get the list of allowed Uniswap pairs", - "returns": - { - "_0": "List of allowed Uniswap pairs" - } - }, - "availableToMint()": - { - "details": "Get the amount of available mintable token" - }, - "calculateRebalanceByDebtReward(uint256)": - { - "details": "@param burnt amount of of uSD burnt" - }, - "differences()": - { - "details": "GET" - }, - "doubleProxy()": - { - "details": "Get the address for the doubleProxy smart contract" - }, - "fromTokenToStable(address,uint256)": - { - "details": "Convert from one of the pooled token to uSD", - "params": - { - "amount": "Of token to be converted", - "tokenAddress": "Address of the token to convert" - }, - "returns": - { - "_0": "Amount of uSD tokens" - } - }, - "init(string,string,address,address[],uint256[],uint256[],uint256[])": - { - "details": "Constructor signature", - "params": - { - "allowedPairs": "list of Uniswap Pairs to be set as whitelisted source tokens", - "doubleProxy": "address for the DoubleProxy", - "mintables": "max amount of mintables inside a timeWindow", - "name": "name of the StableCoin ERC20 token", - "rebalanceRewardMultiplier": "multiplier used to compute how many unifi tokens to mint during uSD rebalance", - "symbol": "ticker for the StableCoin ERC20 token", - "timeWindows": "time windows inside which some time-delimited operations can be performed" - } - }, - "setAllowedPairs(address[])": - { - "details": "Set the whitelisted Uniswap pairs", - "params": - { - "newAllowedPairs": "list of Uniswap pairs to be whitelisted" - } - }, - "setDoubleProxy(address)": - { - "details": "Set a new DoubleProxy", - "params": - { - "newDoubleProxy": "new DoubleProxy to set" - } - }, - "tierData()": - { - "details": "Get all tiers of data of the carried context" - } - }, - "title": "Interface for the \"uSD\" AKA \"uniswap State Dollar\", Unifi stablecoin.", - "version": 1 -} - -======= ../contracts/stableCoin/standalone/IStableCoin.sol:IStateHolder ======= -Developer Documentation -{ - "kind": "dev", - "methods": {}, - "version": 1 -} - -======= ../contracts/stableCoin/standalone/IStableCoin.sol:IUniswapV2Pair ======= -Developer Documentation -{ - "kind": "dev", - "methods": {}, - "title": "Interface", - "version": 1 -} - -======= ../contracts/stableCoin/standalone/IStableCoin.sol:IUniswapV2Router ======= -Developer Documentation -{ - "kind": "dev", - "methods": {}, - "version": 1 -} diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 6247f7e..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..b4829c9 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,29 @@ +site_name: Unifi Docs +docs_dir: md-build +site_dir: build +permalink: True +nav: + - Home: README.md + - Contributing: CONTRIBUTING.md + - API: + - Stable Coin: + - Address: stableCoin/Address.md + - Context: stableCoin/Context.md + - ERC20: stableCoin/ERC20.md + - IDoubleProxy: stableCoin/IDoubleProxy.md + - IERC20: stableCoin/IERC20.md + - IMWDFunctionalitiesManager: stableCoin/IMWDFunctionalitiesManager.md + - IMWDProxy: stableCoin/IMWDProxy.md + - IStableCoin: stableCoin/IStableCoin.md + - IStateHolder: stableCoin/IStateHolder.md + - IUniswapV2Pair: stableCoin/IUniswapV2Pair.md + - IUniswapV2Router: stableCoin/IUniswapV2Router.md + - SafeMath: stableCoin/SafeMath.md + - StableCoin: stableCoin/StableCoin.md +theme: + name: readthedocs + highlightjs: true + hljs_languages: + - yaml + - typescript + - javascript diff --git a/docs/requirements.in b/docs/requirements.in index 08cf9e8..016bb16 100644 --- a/docs/requirements.in +++ b/docs/requirements.in @@ -1,3 +1 @@ -sphinx -sphinxcontrib-soliditydomain -sphinx-rtd-theme +mkdocs diff --git a/docs/requirements.txt b/docs/requirements.txt index d80e570..d9819f7 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -4,34 +4,18 @@ # # pip-compile requirements.in # -alabaster==0.7.12 # via sphinx -antlr4-python3-runtime==4.7.1 # via sphinxcontrib-soliditydomain -babel==2.8.0 # via sphinx -certifi==2020.6.20 # via requests -chardet==3.0.4 # via requests -docutils==0.16 # via sphinx -idna==2.10 # via requests -imagesize==1.2.0 # via sphinx -jinja2==2.11.2 # via sphinx +click==7.1.2 # via mkdocs, nltk +future==0.18.2 # via lunr +jinja2==2.11.2 # via mkdocs +joblib==0.16.0 # via nltk +livereload==2.6.3 # via mkdocs +lunr[languages]==0.5.8 # via mkdocs +markdown==3.2.2 # via mkdocs markupsafe==1.1.1 # via jinja2 -packaging==20.4 # via sphinx -peewee==3.13.3 # via sphinxcontrib-soliditydomain -pygments==2.6.1 # via sphinx -pyparsing==2.4.7 # via packaging -pytz==2020.1 # via babel -requests==2.24.0 # via sphinx -six==1.15.0 # via packaging -snowballstemmer==2.0.0 # via sphinx -sphinx-rtd-theme==0.5.0 # via -r requirements.in -sphinx==3.1.2 # via -r requirements.in, sphinx-rtd-theme -sphinxcontrib-applehelp==1.0.2 # via sphinx -sphinxcontrib-devhelp==1.0.2 # via sphinx -sphinxcontrib-htmlhelp==1.0.3 # via sphinx -sphinxcontrib-jsmath==1.0.1 # via sphinx -sphinxcontrib-qthelp==1.0.3 # via sphinx -sphinxcontrib-serializinghtml==1.1.4 # via sphinx -sphinxcontrib-soliditydomain==0.5.1 # via -r requirements.in -urllib3==1.25.10 # via requests - -# The following packages are considered to be unsafe in a requirements file: -# setuptools +mkdocs==1.1.2 # via -r requirements.in +nltk==3.5 # via lunr +pyyaml==5.3.1 # via mkdocs +regex==2020.7.14 # via nltk +six==1.15.0 # via livereload, lunr +tornado==6.0.4 # via livereload, mkdocs +tqdm==4.48.2 # via nltk diff --git a/docs/solidity-docgen-templates/contract.hbs b/docs/solidity-docgen-templates/contract.hbs new file mode 100644 index 0000000..f934295 --- /dev/null +++ b/docs/solidity-docgen-templates/contract.hbs @@ -0,0 +1,53 @@ +# {{name}} + +{{{natspec.devdoc}}} + +{{#if ownFunctions}} +## Functions: +{{#ownFunctions}} +{{#if (or (eq visibility "public") (eq visibility "external"))}} +- [`{{name}}({{args}})`](#function-{{name}}) +{{/if}} +{{/ownFunctions}} +{{/if}} + +{{#if ownEvents}} +## Events: +{{#ownEvents}} +- [`{{name}}({{args}})`](#event-{{name}}) +{{/ownEvents}} +{{/if}} + +{{#ownFunctions}} +{{#if (or (eq visibility "public") (eq visibility "external"))}} +### Function: {{name}} +`{{name}}({{args}}){{#if outputs}} → {{outputs}}{{/if}}` +#### Description +{{#if natspec.devdoc}}{{natspec.devdoc}}{{else}}No description{{/if}} +{{#if natspec.params}} +#### Parameters: +{{#natspec.params}} +- `{{param}}`: {{description}} +{{/natspec.params}} +{{/if}} +{{#if natspec.returns}} +#### Return Values: +{{#natspec.returns}} +- {{param}} {{description}} +{{/natspec.returns}} +{{/if}} +{{/if}} +{{/ownFunctions}} + +{{#ownEvents}} +### Event: {{name}} +`{{name}}({{args}})` +#### Description +{{#if natspec.devdoc}}{{natspec.devdoc}}{{else}}No description{{/if}} +{{#if natspec.params}} +#### Parameters: +{{#natspec.params}} +- `{{param}}`: {{description}} +{{/natspec.params}} +{{/if}} +{{/ownEvents}} diff --git a/docs/source/api.rst b/docs/source/api.rst deleted file mode 100644 index 90b33a5..0000000 --- a/docs/source/api.rst +++ /dev/null @@ -1,16 +0,0 @@ -############# -API Reference -############# - - -.. autosolinterface:: IStableCoin - :members: - -.. autosolinterface:: IDoubleProxy - :members: - -.. autosolinterface:: IUniswapV2Router - :members: - -.. autosolinterface:: IUniswapV2Pair - :members: diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index c52ed61..0000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,90 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# - -import os -import sys - -sys.path.insert(0, os.path.abspath(".")) - - -# -- Project information ----------------------------------------------------- - -project = "unifi" -copyright = "2020, unifi" -author = "unifi" - - -# The short X.Y version -version = "0.5.0" -# The full version, including alpha/beta/rc tags -release = "0.5.0" - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinxcontrib.soliditydomain", - "sphinx.ext.intersphinx", -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - -# -- Options for HTML output ------------------------------------------------- - -# Logo -html_logo = "" - - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -html_theme_options = { - "display_version": True, - "sticky_navigation": True, - "collapse_navigation": False, - "navigation_depth": 4, - "logo_only": True, -} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] - -html_css_files = ["css/custom.css"] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index e37646e..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. unifi documentation master file, created by - sphinx-quickstart on Thu Aug 6 20:57:06 2020. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to unifi's documentation! -=================================== - -.. toctree:: - :maxdepth: 2 - :caption: Contents:' - - api - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/package.json b/package.json index feeb550..d8a57f0 100644 --- a/package.json +++ b/package.json @@ -10,5 +10,12 @@ "prettier-plugin-solidity": "^1.0.0-alpha.56", "solc": "^0.7.0", "solidity-docgen": "^0.5.4" + }, + "scripts": { + "docs": "yarn docs:clean && yarn docs:docgen && yarn docs:mkdocs", + "docs:clean": "rm -r docs/{md-build,build}", + "docs:docgen": "cd docs && solidity-docgen -i ../contracts -o md-build -t solidity-docgen-templates && cp ../*.md md-build && mv md-build/stableCoin/standalone/* md-build/stableCoin && rm -r md-build/stableCoin/standalone/", + "docs:mkdocs:build": "cd docs && mkdocs build", + "docs:mkdocs:serve": "yarn docs:docgen && cd docs && mkdocs serve" } }