added documentation to README.md and removed book from gitignore

KlimaDAO · Feb 1, 2024 · bbc514d · bbc514d
1 parent 704b462
commit bbc514d
Show file tree

Hide file tree

Showing 511 changed files with 7,068 additions and 1,156 deletions.
diff --git a/.gitignore b/.gitignore
@@ -31,4 +31,5 @@ node_modules
 
 # docs
 # docs/*
-# !docs/preprocess_summary.py
+# !docs/preprocess_summary.py
+docs/.gitignore
diff --git a/README.md b/README.md
@@ -60,3 +60,17 @@ in `metatx/ERC2771ContextUpgradeable.sol` from a private to a public address.
 There is another issue related to the `_trustedForwarder` in that contract that has not yet been resolved.
 
 Since `aKLIMA` was a prelaunch coupon and the existing deployed versino of the redemption contract works as expected, this contract is no longer needed.
+
+## Documentation
+
+This repo is configured with [Foundry](https://book.getfoundry.sh/) to generate documentation for the solidity source files with the [forge doc](https://book.getfoundry.sh/reference/forge/forge-doc) command.
+
+Foundry forge doc generates and builds an mdbook from the natspec comments contained within the Solidity source files.The `book.toml` file located in the root folder contains the config settings and the `preprocess_summary.py` script allows you to customize the book after it is generated.
+
+*If you have not installed Foundry, follow the guide above before proceeding.*
+
+**Please follow these rules:**
+- Annonate your code with [proper NatSpec comments](https://docs.soliditylang.org/en/latest/natspec-format.html)
+- Before committing code, run the `force doc --build` in order to build the doc/book
+
+You can run a local version of the documentation by running `forge doc --serve`
diff --git a/docs/book.toml b/docs/book.toml
@@ -1,16 +1,16 @@
 [book]
-src = "src"
-title = "KlimaDAO solidity reference documentation"
 description = "KlimaDAO smart contract docs auto-generated by Foundry Forge"
 ignore = []
 language = "en"
+src = "src"
+title = "KlimaDAO solidity reference documentation"
 
 [output.html]
-no-section-label = true
-additional-js = ["solidity.min.js"]
 additional-css = ["book.css"]
-git-repository-url = "https://github.com/KlimaDAO/klimadao-solidity"
+additional-js = ["solidity.min.js"]
 default-theme = "coal"
+git-repository-url = "https://github.com/KlimaDAO/klimadao-solidity"
+no-section-label = true
 preferred-dark-theme = "coal"
 
 [output.html.fold]

diff --git a/docs/book/404.html b/docs/book/404.html
@@ -90,11 +90,33 @@
             <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
         </nav>
 
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
         <div id="page-wrapper" class="page-wrapper">
 
             <div class="page">
                                 <div id="menu-bar-hover-placeholder"></div>
-                <div id="menu-bar" class="menu-bar sticky bordered">
+                <div id="menu-bar" class="menu-bar sticky">
                     <div class="left-buttons">
                         <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                             <i class="fa fa-bars"></i>

diff --git a/docs/book/book.js b/docs/book/book.js
@@ -68,7 +68,7 @@ function playground_text(playground, hidden = true) {
     }
 
     // updates the visibility of play button based on `no_run` class and
-    // used crates vs ones available on http://play.rust-lang.org
+    // used crates vs ones available on https://play.rust-lang.org
     function update_play_button(pre_block, playground_crates) {
         var play_button = pre_block.querySelector(".play-button");
 
@@ -179,7 +179,7 @@ function playground_text(playground, hidden = true) {
     // even if highlighting doesn't apply
     code_nodes.forEach(function (block) { block.classList.add('hljs'); });
 
-    Array.from(document.querySelectorAll("code.language-rust")).forEach(function (block) {
+    Array.from(document.querySelectorAll("code.hljs")).forEach(function (block) {
 
         var lines = Array.from(block.querySelectorAll('.boring'));
         // If no lines were hidden, return
@@ -346,7 +346,7 @@ function playground_text(playground, hidden = true) {
         }
 
         setTimeout(function () {
-            themeColorMetaTag.content = getComputedStyle(document.body).backgroundColor;
+            themeColorMetaTag.content = getComputedStyle(document.documentElement).backgroundColor;
         }, 1);
 
         if (window.ace && window.editors) {
@@ -551,13 +551,6 @@ function playground_text(playground, hidden = true) {
             firstContact = null;
         }
     }, { passive: true });
-
-    // Scroll sidebar to current active section
-    var activeSection = document.getElementById("sidebar").querySelector(".active");
-    if (activeSection) {
-        // https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView
-        activeSection.scrollIntoView({ block: 'center' });
-    }
 })();
 
 (function chapterNavigation() {
@@ -676,13 +669,14 @@ function playground_text(playground, hidden = true) {
         }, { passive: true });
     })();
     (function controllBorder() {
-        menu.classList.remove('bordered');
-        document.addEventListener('scroll', function () {
+        function updateBorder() {
             if (menu.offsetTop === 0) {
                 menu.classList.remove('bordered');
             } else {
                 menu.classList.add('bordered');
             }
-        }, { passive: true });
+        }
+        updateBorder();
+        document.addEventListener('scroll', updateBorder, { passive: true });
     })();
 })();
diff --git a/docs/book/css/general.css b/docs/book/css/general.css
@@ -5,6 +5,7 @@
 :root {
     /* Browser default font-size is 16px, this way 1 rem = 10px */
     font-size: 62.5%;
+    color-scheme: var(--color-scheme);
 }
 
 html {

diff --git a/docs/book/css/print.css b/docs/book/css/print.css
@@ -22,14 +22,6 @@
     overflow-y: initial;
 }
 
-code {
-    background-color: #666666;
-    border-radius: 5px;
-
-    /* Force background to be printed in Chrome */
-    -webkit-print-color-adjust: exact;
-}
-
 pre > .buttons {
     z-index: 2;
 }

diff --git a/docs/book/css/variables.css b/docs/book/css/variables.css
@@ -50,6 +50,8 @@
     --searchresults-border-color: #888;
     --searchresults-li-bg: #252932;
     --search-mark-bg: #e3b171;
+
+    --color-scheme: dark;
 }
 
 .coal {
@@ -90,6 +92,8 @@
     --searchresults-border-color: #98a3ad;
     --searchresults-li-bg: #2b2b2f;
     --search-mark-bg: #355c7d;
+
+    --color-scheme: dark;
 }
 
 .light {
@@ -130,6 +134,8 @@
     --searchresults-border-color: #888;
     --searchresults-li-bg: #e4f2fe;
     --search-mark-bg: #a2cff5;
+
+    --color-scheme: light;
 }
 
 .navy {
@@ -170,6 +176,8 @@
     --searchresults-border-color: #5c5c68;
     --searchresults-li-bg: #242430;
     --search-mark-bg: #a2cff5;
+
+    --color-scheme: dark;
 }
 
 .rust {
@@ -210,6 +218,8 @@
     --searchresults-border-color: #888;
     --searchresults-li-bg: #dec2a2;
     --search-mark-bg: #e69f67;
+
+    --color-scheme: light;
 }
 
 @media (prefers-color-scheme: dark) {

diff --git a/docs/book/index.html b/docs/book/index.html
@@ -89,11 +89,33 @@
             <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
         </nav>
 
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
         <div id="page-wrapper" class="page-wrapper">
 
             <div class="page">
                                 <div id="menu-bar-hover-placeholder"></div>
-                <div id="menu-bar" class="menu-bar sticky bordered">
+                <div id="menu-bar" class="menu-bar sticky">
                     <div class="left-buttons">
                         <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                             <i class="fa fa-bars"></i>
@@ -192,6 +214,14 @@ <h2 id="deprecated-contracts"><a class="header" href="#deprecated-contracts">Dep
 in <code>metatx/ERC2771ContextUpgradeable.sol</code> from a private to a public address.</p>
 <p>There is another issue related to the <code>_trustedForwarder</code> in that contract that has not yet been resolved.</p>
 <p>Since <code>aKLIMA</code> was a prelaunch coupon and the existing deployed versino of the redemption contract works as expected, this contract is no longer needed.</p>
+<h2 id="documentation"><a class="header" href="#documentation">Documentation</a></h2>
+<p>This repo is configured with <a href="https://book.getfoundry.sh/">Foundry</a> to generate documentation for the solidity source files with the <a href="https://book.getfoundry.sh/reference/forge/forge-doc">forge doc</a> command. If you have not installed Foundry, follow the guide above.</p>
+<p><strong>Please follow these rules:</strong></p>
+<ul>
+<li>Annonate your code with <a href="https://docs.soliditylang.org/en/latest/natspec-format.html">proper NatSpec comments</a></li>
+<li>Before committing code, run the <code>force doc --build</code> in order to build the doc/book</li>
+</ul>
+<p>You can run a local version of the documentation by running <code>forge doc --serve</code></p>
 
                     </main>
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,6 +5,7 @@ @@
     :root {
         /* Browser default font-size is 16px, this way 1 rem = 10px */
         font-size: 62.5%;
+        color-scheme: var(--color-scheme);
     }
     html {
@@ Expand Down @@