Restructure docs generation around mkdocs

Author: mr-ubik

.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

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
+```
+
+### 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/

README.md

@@ -0,0 +1,3 @@
+# unifi
+
+A DFO protocol powered DeFi set of tools built on top of Uniswap.

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 {

contracts/stableCoin/standalone/IDoubleProxy.sol

@@ -0,0 +1,6 @@
+pragma solidity ^0.6.0;
+
+// DOCUMENT
+interface IDoubleProxy {
+    function proxy() external view returns (address);
+}

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);
+}

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);
+}

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);
 }

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);
+}

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
+        );
+}