HB Book - Literate Erlang Docs

.github/workflows/build-deploy-docs.yml

@@ -1,20 +1,24 @@
-name: 🥘 Build & Deploy Docs HB
+name: 🥘 Build & Deploy mkdocs Documentation
 
 on:
   pull_request:
     branches:
-      - main
+      - docs/deploy
+      - docs/deploy-test
     paths:
       # Trigger on changes to docs, mkdocs config, or the workflow itself
       - "docs/**"
+      - "!docs/book/**"
       - "mkdocs.yml"
       - ".github/workflows/build-deploy-docs.yml"
   push:
     branches:
-      - main
+      - docs/deploy
+      - docs/deploy-test
     paths:
       # Trigger on changes to docs, mkdocs config, or the workflow itself
       - "docs/**"
+      - "!docs/book/**"
       - "mkdocs.yml"
       - ".github/workflows/build-deploy-docs.yml"
 
@@ -52,6 +56,7 @@ jobs:
           . ~/otp-27.0/activate
           echo "Erlang version:"
           erl -eval 'io:format("~s~n", [erlang:system_info(otp_release)]), halt().'
+
       # Install system dependencies needed for HyperBEAM
       - name: Install system dependencies
         run: |
@@ -62,15 +67,19 @@ jobs:
             ncurses-dev \
             libssl-dev \
             ca-certificates
+
       # Debug step - display the region with syntax error
       - name: Debug syntax error region
         run: |
           echo "Showing the region with syntax error in hb_message.erl:"
           sed -n '1440,1460p' src/hb_message.erl || echo "File not found or cannot be read"
+
           echo "Checking for syntax error fix files:"
           find . -name "*.erl.fix" -o -name "hb_message.erl.*" | grep -v ".beam" || echo "No fix files found"
+
           echo "Erlang version:"
           . ~/otp-27.0/activate && erl -eval 'io:format("~s~n", [erlang:system_info(otp_release)]), halt().'
+
       # Install rebar3
       - name: Install rebar3
         run: |
@@ -79,12 +88,14 @@ jobs:
           curl -O https://s3.amazonaws.com/rebar3/rebar3 && chmod +x rebar3
           sudo mv rebar3 /usr/local/bin/rebar3
           . ~/otp-27.0/activate && rebar3 --version
+
       # Install Rust toolchain (needed for WASM components)
       - name: Install Rust and Cargo
         run: |
           curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
           echo "$HOME/.cargo/bin" >> $GITHUB_PATH
           source "$HOME/.cargo/env"
+
       # Setup Node.js
       - name: ⎔ Setup Node
         uses: actions/setup-node@v3
@@ -96,18 +107,20 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin
-      - name: 🛠 Build Docs
+
+      - name: 🛠 Build mkdocs Documentation
         run: |
           . ~/otp-27.0/activate
           SKIP_COMPILE=1 SKIP_EDOC=1 ./docs/build-all.sh -v
+
   # Build and deploy the artifacts to Arweave via ArDrive
   deploy:
-    if: github.ref == 'refs/heads/main'
+    if: github.ref == 'refs/heads/docs/deploy' || github.ref == 'refs/heads/docs/deploy-test'
     runs-on: ubuntu-22.04
     # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
     # However, do NOT cancel in-progress runs as we want to allow these deployments to complete.
     concurrency:
-      group: deploy
+      group: deploy-mkdocs
       cancel-in-progress: false
     steps:
       - name: ⬇️ Checkout repo
@@ -131,6 +144,7 @@ jobs:
           . ~/otp-27.0/activate
           echo "Erlang version:"
           erl -eval 'io:format("~s~n", [erlang:system_info(otp_release)]), halt().'
+
       # Install system dependencies needed for HyperBEAM
       - name: Install system dependencies
         run: |
@@ -141,15 +155,19 @@ jobs:
             ncurses-dev \
             libssl-dev \
             ca-certificates
+
       # Debug step - display the region with syntax error
       - name: Debug syntax error region
         run: |
           echo "Showing the region with syntax error in hb_message.erl:"
           sed -n '1440,1460p' src/hb_message.erl || echo "File not found or cannot be read"
+
           echo "Checking for syntax error fix files:"
           find . -name "*.erl.fix" -o -name "hb_message.erl.*" | grep -v ".beam" || echo "No fix files found"
+
           echo "Erlang version:"
           . ~/otp-27.0/activate && erl -eval 'io:format("~s~n", [erlang:system_info(otp_release)]), halt().'
+
       # Install rebar3
       - name: Install rebar3
         run: |
@@ -158,17 +176,20 @@ jobs:
           curl -O https://s3.amazonaws.com/rebar3/rebar3 && chmod +x rebar3
           sudo mv rebar3 /usr/local/bin/rebar3
           . ~/otp-27.0/activate && rebar3 --version
+
       # Install Rust toolchain (needed for WASM components)
       - name: Install Rust and Cargo
         run: |
           curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
           echo "$HOME/.cargo/bin" >> $GITHUB_PATH
           source "$HOME/.cargo/env"
+
       # Install pip dependencies and cache them
       - name: 📦 Install Python dependencies
         run: |
           python -m pip install --upgrade pip
           pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin
+
       # Setup Node.js (needed for npx deploy command)
       - name: ⎔ Setup Node
         uses: actions/setup-node@v3
@@ -184,21 +205,34 @@ jobs:
           VER=`node --version`; echo "Node ver:   $VER"
           VER=`npm --version`; echo "npm ver:    $VER"
           . ~/otp-27.0/activate && erl -eval 'io:format("Erlang OTP version: ~s~n", [erlang:system_info(otp_release)]), halt().'
-      - name: 🛠 Build Docs
+
+      - name: 🛠 Build mkdocs Documentation
         id: build_artifacts
         run: |
           . ~/otp-27.0/activate
           SKIP_COMPILE=1 SKIP_EDOC=1 ./docs/build-all.sh -v
           touch mkdocs-site/.nojekyll
+
           echo "artifacts_output_dir=mkdocs-site" >> $GITHUB_OUTPUT
+
       - name: 💾 Publish to Arweave
         id: publish_artifacts
         run: |
-          npx permaweb-deploy \
-            --arns-name=dps-testing-facility \
-            --ant-process=${{ secrets.ANT_PROCESS }} \
-            --deploy-folder=${ARTIFACTS_OUTPUT_DIR}
+          if [[ "${{ github.ref }}" == "refs/heads/docs/deploy" ]]; then
+            echo "Deploying to production ArNS"
+            npx permaweb-deploy \
+              --arns-name=hyperbeam \
+              --ant-process=${{ secrets.ANT_PROCESS }} \
+              --deploy-folder=${ARTIFACTS_OUTPUT_DIR}
+          elif [[ "${{ github.ref }}" == "refs/heads/docs/deploy-test" ]]; then
+            echo "Deploying to preview ArNS undername"
+            npx permaweb-deploy \
+              --arns-name=hyperbeam \
+              --undername=preview \
+              --ant-process=${{ secrets.ANT_PROCESS }} \
+              --deploy-folder=${ARTIFACTS_OUTPUT_DIR}
+          fi
         env:
           DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
           ARTIFACTS_OUTPUT_DIR: ${{ steps.build_artifacts.outputs.artifacts_output_dir }}
-          ANT_PROCESS: ${{ secrets.ANT_PROCESS }}
+          ANT_PROCESS: ${{ secrets.ANT_PROCESS }}

.github/workflows/build-deploy-mdbook.yml

@@ -0,0 +1,117 @@
+name: 📖 Build & Deploy mdBook Documentation
+
+on:
+  pull_request:
+    branches:
+      - edge
+    paths:
+      # Trigger on changes to source code, mdbook config, or the workflow itself
+      - "src/**"
+      - "docs/book/book.toml"
+      - "docs/book/custom.css"
+      - "docs/book/custom.js"
+      - "docs/generate-literate-docs.sh"
+      - ".github/workflows/build-deploy-mdbook.yml"
+  push:
+    branches:
+      - edge
+    paths:
+      # Trigger on changes to source code, mdbook config, or the workflow itself
+      - "src/**"
+      - "docs/book/book.toml"
+      - "docs/book/custom.css"
+      - "docs/book/custom.js"
+      - "docs/generate-literate-docs.sh"
+      - ".github/workflows/build-deploy-mdbook.yml"
+
+  # Perform a release using a workflow dispatch
+  workflow_dispatch:
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  # Run the build as part of PRs to confirm the site properly builds
+  check_build:
+    if: ${{ startsWith(github.ref, 'refs/pull/') }}
+    runs-on: ubuntu-22.04
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v3
+
+      # Install mdBook for literate documentation
+      - name: 📖 Install mdBook
+        run: |
+          curl -L https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz | tar xz
+          chmod +x mdbook
+          sudo mv mdbook /usr/local/bin/mdbook
+          mdbook --version
+
+      - name: 📝 Generate Literate Erlang Documentation
+        run: |
+          ./docs/generate-literate-docs.sh -v
+
+      - name: 📚 Build mdBook Documentation
+        run: |
+          cd docs/book && mdbook build
+
+  # Build and deploy the mdBook to Arweave
+  deploy:
+    if: github.ref == 'refs/heads/edge'
+    runs-on: ubuntu-22.04
+    # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+    # However, do NOT cancel in-progress runs as we want to allow these deployments to complete.
+    concurrency:
+      group: deploy-mdbook
+      cancel-in-progress: false
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v3
+
+      # Setup Node.js (needed for npx deploy command)
+      - name: ⎔ Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 22
+
+      - name: 👀 Env
+        run: |
+          echo "Event name: ${{ github.event_name }}"
+          echo "Git ref:    ${{ github.ref }}"
+          echo "GH actor:   ${{ github.actor }}"
+          echo "SHA:        ${{ github.sha }}"
+          VER=`node --version`; echo "Node ver:   $VER"
+          VER=`npm --version`; echo "npm ver:    $VER"
+
+      # Install mdBook for literate documentation
+      - name: 📖 Install mdBook
+        run: |
+          curl -L https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz | tar xz
+          chmod +x mdbook
+          sudo mv mdbook /usr/local/bin/mdbook
+          mdbook --version
+
+      - name: 📝 Generate Literate Erlang Documentation
+        run: |
+          ./docs/generate-literate-docs.sh -v
+
+      - name: 📚 Build mdBook Documentation
+        id: build_mdbook
+        run: |
+          cd docs/book && mdbook build
+          cd ../..
+          echo "mdbook_output_dir=docs/book/dist" >> $GITHUB_OUTPUT
+
+      - name: 📖 Publish mdBook to Arweave
+        id: publish_mdbook
+        run: |
+          npx permaweb-deploy \
+            --arns-name=hyperbeam \
+            --undername=book \
+            --ant-process=${{ secrets.ANT_PROCESS }} \
+            --deploy-folder=${MDBOOK_OUTPUT_DIR}
+        env:
+          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+          MDBOOK_OUTPUT_DIR: ${{ steps.build_mdbook.outputs.mdbook_output_dir }}
+          ANT_PROCESS: ${{ secrets.ANT_PROCESS }}

.gitignore

@@ -43,6 +43,13 @@ mkdocs-site/
 mkdocs-site-id.txt
 mkdocs-site-manifest.csv
 
+# mdbook generated documentation
+docs/book/dist/
+
+# Generated literate Erlang documentation files
+docs/literate-erlang/
+docs/book/src/*.erl.md
+
 !test/admissible-report-wallet.json
 !test/admissible-report.json
 !test/config.json

docs/README.md

@@ -1,7 +1,13 @@
-
 ## Documentation
 
-HyperBEAM uses [MkDocs](https://www.mkdocs.org/) with the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme to build its documentation site.
+HyperBEAM uses two documentation systems:
+
+1. **[MkDocs](https://www.mkdocs.org/)** - Main documentation site with Material theme
+2. **[mdBook](https://rust-lang.github.io/mdBook/)** - Literate programming documentation generated from Erlang source
+
+## MkDocs Documentation
+
+The main documentation site uses MkDocs with the Material for MkDocs theme.
 
 Building the documentation requires Python 3 and pip. It's recommended to use a virtual environment:
 
@@ -52,6 +58,31 @@ Press `Ctrl+C` in the terminal where the server is running to stop it.
 
 The final static site is generated in the `mkdocs-site` directory, as configured in `mkdocs.yml` (`site_dir: mkdocs-site`).
 
+## mdBook Documentation (Literate Programming)
+
+The literate programming documentation system generates browsable documentation directly from Erlang source code comments.
+
+**Live Site:** [hyperbeam.arweave.dev/book](https://hyperbeam.arweave.dev/book)
+
+### Quick Start
+
+```bash
+# Generate literate docs and build the book (integrated workflow)
+./docs/build-literate-erlang.sh    # Generate .erl.md files and copy to mdBook
+cd docs/book && mdbook build       # Build the documentation site
+cd docs/book && mdbook serve       # Serve locally on http://localhost:3471
+```
+
+### Automated Deployment
+
+Documentation is automatically deployed via GitHub Actions:
+
+- **Triggers**: Pushes to `edge` branch affecting `src/**` or mdBook configuration
+- **Process**: Generates fresh documentation from source → builds mdBook → deploys to ArNS
+- **URL**: [hyperbeam.arweave.dev/book](https://hyperbeam.arweave.dev/book)
+
+For complete mdBook documentation details, see [book/README.md](book/README.md).
+
 ### Contributing to the Documentation
 
 To contribute documentation to HyperBEAM, follow these steps:
@@ -112,4 +143,4 @@ To contribute documentation to HyperBEAM, follow these steps:
    - Be prepared to make adjustments based on feedback
    - Once approved, your documentation will be merged into the main repository
 
-For more detailed contribution guidelines, see the [Community Guidelines](./docs/misc/community/guidelines.md) and [Development Setup](./docs/misc/community/setup.md) documentation.
+For more detailed contribution guidelines, see the [Community Guidelines](./docs/misc/community/guidelines.md) and [Development Setup](./docs/misc/community/setup.md) documentation.