diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 0000000..e84577d --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index 872f77b..8f72f28 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,7 @@ docs config/local.ts .DS_Store .idea + +# github pages +_site/ + diff --git a/Readme.md b/Readme.md index 62602a3..307c454 100644 --- a/Readme.md +++ b/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. diff --git a/contracts/NodeManagement.sol b/contracts/NodeManagement.sol index b389774..7199497 100644 --- a/contracts/NodeManagement.sol +++ b/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 } } diff --git a/docs-template/md2html.sh b/docs-template/md2html.sh new file mode 100755 index 0000000..55df16d --- /dev/null +++ b/docs-template/md2html.sh @@ -0,0 +1,58 @@ +#!/bin/bash + +# Check for correct number of arguments +if [ "$#" -ne 2 ]; then + echo "Usage: $0 " + 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." diff --git a/docs-template/style.css b/docs-template/style.css new file mode 100644 index 0000000..c0fce4b --- /dev/null +++ b/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; +} \ No newline at end of file diff --git a/docs-template/template.html b/docs-template/template.html new file mode 100644 index 0000000..486beb2 --- /dev/null +++ b/docs-template/template.html @@ -0,0 +1,101 @@ + + + + + + + $if(title)$$title$$endif$ + + + +$if(template_css)$ + +$else$ + +$endif$ + + + + + + + + + + + + + + $for(author-meta)$ + + $endfor$ + $if(date-meta)$ + + $endif$ + $if(title-prefix)$$title-prefix$ - $endif$$pagetitle$ + + $if(quotes)$ + + $endif$ + $if(highlighting-css)$ + + $endif$ + $for(css)$ + + $endfor$ + $if(math)$ + $math$ + $endif$ + $for(header-includes)$ + $header-includes$ + $endfor$ + + + + + +
+ + $if(title)$ +
+
+

$title$

+ $if(date)$ +

$date$

+ $endif$ + $for(author)$ +

$author$

+ $endfor$ +
+
+ $endif$ + +
+
+
+
+ + $if(toc)$ + $toc$ + $endif$ + +
+
+
+ +
+ + $if(abstract)$ +

$abstract-title$

+ $abstract$ + $endif$ + +$body$ +
+
+ +
+ + \ No newline at end of file