Feat/publish docs

.github/workflows/publish-docs.yml

@@ -0,0 +1,73 @@
+name: Pushlish docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - feat/publish-docs
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one instance of wf to run at once
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+env:
+  MARKDOWN_PATH: "./docs/"
+  HTML_PATH: "./_site/"
+
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Use Node v20
+        uses: actions/setup-node@v3
+        with:
+          node-version-file: .nvmrc
+          cache: "yarn"
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Compile contracts
+        run: yarn compile
+
+      - name: Generate markdown documentation
+        run: yarn generate-docs
+
+      - name: Install Pandoc
+        run: sudo apt-get install pandoc
+
+      - name: Build HTML documentation
+        run: |
+          chmod +x ./docs-template/md2html.sh
+          ./docs-template/md2html.sh ${{ env.MARKDOWN_PATH }} ${{ env.HTML_PATH }}
+
+      - name: Setup pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifacts
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ${{ env.HTML_PATH }}
+
+  deploy-docs:
+    environment:
+        name: github-pages
+        url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: generate-docs
+    name: Deploy to GitHub Pages
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -16,3 +16,7 @@ docs
 config/local.ts
 .DS_Store
 .idea
+
+# github pages
+_site/
+

Readme.md

@@ -155,6 +155,16 @@ Note that slither does not seem to be working with the repo as-is, resulting in
 slither.solc_parsing.exceptions.ParsingError: Type not found struct Checkpoints.Trace208
 ```
 
+### Documentation
+
+To generate the solidity documentation:
+
+```bash
+yarn generate-docs
+```
+
+The same documentation is available at github pages: [GithubPages](https://vechain.github.io/vebetterdao-contracts/)
+
 # Disclaimer
 
 This repository is for educational and demonstration purposes. The maintainers are not liable for any misuse or faults within the code.

contracts/NodeManagement.sol

@@ -33,11 +33,11 @@ contract NodeManagement is INodeManagement, AccessControlUpgradeable, UUPSUpgrad
   /**
    * @notice Retrieve the storage reference for node delegation data.
    * @dev Internal pure function to get the storage slot for node delegation data using inline assembly.
-   * @return $ The storage reference for node delegation data.
+   * @return storageReference The storage reference for node delegation data.
    */
-  function _getNodeManagementStorage() internal pure returns (NodeManagementStorage storage $) {
+  function _getNodeManagementStorage() internal pure returns (NodeManagementStorage storage storageReference) {
     assembly {
-      $.slot := NodeManagementStorageLocation
+      storageReference.slot := NodeManagementStorageLocation
     }
   }
 

docs-template/md2html.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+# Check for correct number of arguments
+if [ "$#" -ne 2 ]; then
+    echo "Usage: $0 <input_dir> <output_dir>"
+    exit 1
+fi
+
+# Set input and output directories from command-line arguments
+INPUT_DIR="$1"
+OUTPUT_DIR="$2"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Set input and output directories
+CSS_FILE="$SCRIPT_DIR/style.css"
+TEMPLATE_HTML="$SCRIPT_DIR/template.html"
+INDEX_MD="$INPUT_DIR/index.md"
+
+
+# Ensure the output directory exists
+mkdir -p "$OUTPUT_DIR"
+
+# Check if the CSS file exists
+if [ ! -f "$CSS_FILE" ]; then
+    echo "Error: CSS file '$CSS_FILE' not found!"
+    exit 1
+fi
+
+# Check if the template html file exists
+if [ ! -f "$TEMPLATE_HTML" ]; then
+    echo "Error: Template file '$TEMPLATE_HTML' not found!"
+    exit 1
+fi
+
+# Create an index.md file
+echo "# VeBetterDao Contracts" > "$INDEX_MD"
+echo "" >> "$INDEX_MD"
+for file in ./docs/*.md; do
+    base_name="$(basename "${file%.md}")"
+    echo "- [${base_name}](./${base_name}.html)" >> "$INDEX_MD"
+done
+
+# Loop through all Markdown files in the input directory
+for file in "$INPUT_DIR"/*.md; do
+    # Extract the base filename (e.g., "file.md" -> "file.html")
+    output_file="$OUTPUT_DIR/$(basename "${file%.md}.html")"
+
+    # Convert the Markdown file to HTML with a Table of Contents
+    pandoc "$file" -o "$output_file" --toc --toc-depth=3 --css="$CSS_FILE" --standalone --template="$TEMPLATE_HTML"
+
+    # Print the file being processed
+    echo "Converted: $file -> $output_file"
+done
+
+
+
+
+echo "All files converted! HTML files are in $OUTPUT_DIR."

docs-template/style.css

@@ -0,0 +1,30 @@
+body {
+    font-family: 'Inter', sans-serif;
+    line-height: 1.6;
+    margin: 20px;
+}
+
+h1, h2, h3 {
+    color: #333;
+}
+
+#TOC {
+    background: #f9f9f9;
+    border: 1px solid #ddd;
+    padding: 10px;
+    margin-bottom: 20px;
+}
+
+#TOC ul {
+    list-style: none;
+    padding-left: 15px;
+}
+
+#TOC a {
+    text-decoration: none;
+    color: #007BFF;
+}
+
+#TOC a:hover {
+    text-decoration: underline;
+}

docs-template/template.html

@@ -0,0 +1,101 @@
+<!DOCTYPE html>
+<html $if(lang)$ lang="$lang$" $endif$ dir="ltr">
+
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <title>$if(title)$$title$$endif$</title>
+        <link rel="shortcut icon" href="images/favicon.ico" type="image/x-icon">
+        <link rel="apple-touch-icon-precomposed" href="images/apple-touch-icon.png">
+
+$if(template_css)$
+<link rel="stylesheet" href="$template_css$">
+$else$
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/uikit/2.26.4/css/uikit.gradient.css">
+$endif$
+
+        <!-- <link rel="stylesheet" href="style.css"> -->
+        <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/diversen/pandoc-uikit@master/style.css">
+        <link href="https://vjs.zencdn.net/5.4.4/video-js.css" rel="stylesheet" />
+        <script src="https://code.jquery.com/jquery-2.2.1.min.js"></script>
+        <!-- <script src="uikit.js"></script> -->
+        <script src="https://cdn.jsdelivr.net/gh/diversen/pandoc-uikit@master/uikit.js"></script>
+        <!-- <script src="scripts.js"></script> -->
+        <script src="https://cdn.jsdelivr.net/gh/diversen/pandoc-uikit@master/scripts.js"></script>
+        <!-- <script src="jquery.sticky-kit.js "></script> -->
+        <script src="https://cdn.jsdelivr.net/gh/diversen/pandoc-uikit@master/jquery.sticky-kit.js"></script>
+
+        <meta name="generator" content="pandoc-uikit" />
+        $for(author-meta)$
+        <meta name="author" content="$author-meta$" />
+        $endfor$
+        $if(date-meta)$
+        <meta name="date" content="$date-meta$" />
+        $endif$
+        <title>$if(title-prefix)$$title-prefix$ - $endif$$pagetitle$</title>
+        <style type="text/css">code{white-space: pre;}</style>
+        $if(quotes)$
+        <style type="text/css">q { quotes: "“" "”" "‘" "’"; }</style>
+        $endif$
+        $if(highlighting-css)$
+        <style type="text/css">
+            $highlighting-css$
+        </style>
+        $endif$
+        $for(css)$
+        <link rel="stylesheet" href="$css$" $if(html5)$$else$type="text/css" $endif$/>
+              $endfor$
+              $if(math)$
+              $math$
+              $endif$
+              $for(header-includes)$
+              $header-includes$
+              $endfor$   
+    </head>
+
+    <body>
+
+
+        <div class="uk-container uk-container-center uk-margin-top uk-margin-large-bottom">
+
+            $if(title)$
+            <div class="uk-grid" data-uk-grid-margin>
+                <div class="uk-width-1-1">
+                    <h1 class="uk-heading-large">$title$</h1>
+                    $if(date)$
+                    <h3 class="uk-heading-large">$date$</p></h3>
+                    $endif$
+                    $for(author)$
+                    <p class="uk-text-large">$author$</p>
+                    $endfor$
+                </div>
+            </div>
+            $endif$
+
+            <div class="uk-grid" data-uk-grid-margin >          
+                <div class="uk-width-medium-1-4">
+                    <div class="uk-overflow-container" data-uk-sticky="{top:25,media: 768}">
+                        <div class="uk-panel uk-panel-box menu-begin" >
+
+                            $if(toc)$
+                            $toc$
+                            $endif$
+
+                        </div>
+                    </div>
+                </div>
+
+                <div class="uk-width-medium-3-4">
+
+                    $if(abstract)$
+                        <H1>$abstract-title$</H1>
+                        $abstract$
+                    $endif$
+
+$body$                    
+                </div>
+            </div>
+            <script src="https://vjs.zencdn.net/5.4.4/video.js"></script>
+        </div>
+    </body>
+</html>