Merge pull request #249 from permaweb/dpshade/new-docs-updates

Documentation Site Foundations: Build Pipeline and UI Updates

Author: samcamwilliams

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

@@ -0,0 +1,113 @@
+name: 🥘 Build & Deploy Docs HB
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      # Trigger on changes to docs, mkdocs config, or the workflow itself
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/build-deploy-docs.yml"
+  push:
+    branches:
+      - main
+    paths:
+      # Trigger on changes to docs, mkdocs config, or the workflow itself
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/build-deploy-docs.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-latest
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v3
+
+      # Setup Python environment
+      - name: 🐍 Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x' # Use a recent Python 3 version
+
+      # 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
+
+      - name: 🛠 Build Docs
+        run: |
+          ./docs/build-all.sh
+
+  # Build and deploy the artifacts to Arweave via ArDrive
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    # 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
+      cancel-in-progress: false
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v3
+
+      # Setup Python environment
+      - name: 🐍 Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      # 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
+        with:
+          node-version: 22 # Or your preferred version
+          # cache: yarn # Caching might not be needed just for npx
+
+      - 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"
+
+      - name: 🛠 Build Docs
+        id: build_artifacts
+        run: |
+          ./docs/build-all.sh
+          touch mkdocs-site/.nojekyll
+
+          echo "artifacts_output_dir=mkdocs-site" >> $GITHUB_OUTPUT
+
+      - name: 💾 Publish to Arweave
+        id: publish_artifacts
+        run: |
+          npx permaweb-deploy \
+            --ant-process=${ANT_PROCESS} \
+            --undername=${UNDERNAME} \
+            --deploy-folder=${ARTIFACTS_OUTPUT_DIR}
+        env:
+          DEPLOY_KEY: ${{ secrets.CI_WALLET }}
+          ARTIFACTS_OUTPUT_DIR: ${{ steps.build_artifacts.outputs.artifacts_output_dir }}
+          ANT_PROCESS: HY021r2MQL9Zi0qSNFAQ9QRshIc2mNPYf65pZBP04cE
+          UNDERNAME: docs

.gitignore

@@ -19,6 +19,7 @@ logs
 *.iml
 rebar3.crashdump
 *~
+/venv
 
 *.json
 !.vscode/*
@@ -37,4 +38,6 @@ cache-*
 *.svg
 
 cu/
-mkdocs-site/
+mkdocs-site/
+mkdocs-site-id.txt
+mkdocs-site-manifest.csv

README.md

@@ -278,19 +278,29 @@ guide.
 
 HyperBEAM uses [MkDocs](https://www.mkdocs.org/) with the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme to build its documentation site.
 
-Building the documentation requires Python 3, pip, and the following packages:
+Building the documentation requires Python 3 and pip. It's recommended to use a virtual environment:
+
 ```bash
-pip3 install mkdocs mkdocs-material
+# Create and activate a virtual environment (optional but recommended)
+python3 -m venv venv
+source venv/bin/activate  # (macOS/Linux) On Windows use `venv\Scripts\activate`
+
+# Install required packages
+pip3 install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin
+
+# Deactivate the virtual environment when done
+# deactivate
 ```
 
 - **Source Files:** All documentation source files (Markdown `.md`, images, CSS) are located in the `docs/` directory.
 - **Source Code Docs:** Erlang source code documentation is generated using `rebar3 edoc` (with the `edown_doclet` plugin) into the `docs/source-code-docs/` directory as Markdown files. These are then incorporated into the main MkDocs site.
 - **Build Script:** The entire process (compiling, generating edoc, processing source docs, building the site) is handled by the `./docs/build-all.sh` script.
 
-To build and view the documentation locally:
+To build the documentation locally:
 
 1.  Ensure you are in the project root directory.
-2.  Run the build script:
+2.  If using a virtual environment, make sure it's activated.
+3.  Run the build script:
     ```bash
     ./docs/build-all.sh
     ```
@@ -299,9 +309,82 @@ This script performs the following steps:
 - Compiles the Erlang project (`rebar3 compile`).
 - Generates Markdown documentation from source code comments (`rebar3 edoc`) into `docs/source-code-docs/`.
 - Processes the generated source code Markdown files (updates index, cleans up TOCs).
-- Builds the MkDocs site into the `dist/mkdocs` directory (`mkdocs build`).
-- Starts a local development server (`mkdocs serve`) to view the site at `http://127.0.0.1:8000/`.
+- Builds the MkDocs site into the `mkdocs-site` directory (`mkdocs build`).
 
-Press `Ctrl+C` in the terminal where the script is running to stop the local server.
+To view the built documentation locally:
 
-The final static site is generated in the `dist/mkdocs` directory, as configured in `mkdocs.yml` (`site_dir: dist/mkdocs`).
+1.  Navigate to the site directory:
+    ```bash
+    cd mkdocs-site
+    ```
+2.  Start a simple Python HTTP server:
+    ```bash
+    python3 -m http.server 8000
+    ```
+3.  Open your web browser and go to `http://127.0.0.1:8000/`.
+
+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`).
+
+### Contributing to the Documentation
+
+To contribute documentation to HyperBEAM, follow these steps:
+
+1. **Fork the Repository**
+   - Fork the [HyperBEAM repository](https://github.com/permaweb/HyperBEAM) to your GitHub account
+
+2. **Choose the Right Location**
+   - Review the existing documentation structure in `./docs/` to determine the appropriate location for your content
+   - Documentation is organized into several main sections:
+     - `overview/`: High-level concepts and architecture
+     - `installation-core/`: Setup and configuration guides
+     - `components/`: Detailed component documentation
+     - `usage/`: Tutorials and usage guides
+     - `resources/`: Reference materials and source code documentation
+     - `community/`: Contribution guidelines and community resources
+
+3. **Create Your Documentation**
+   - Create a new Markdown file (`.md`) in the appropriate directory
+   - Follow the existing documentation style and format
+   - Use proper Markdown syntax and include:
+     - Clear headings and subheadings
+     - Code blocks with appropriate language specification
+     - Links to related documentation
+     - Images (if needed) in the `docs/assets/` directory
+
+4. **Update the Navigation**
+   - Edit `mkdocs.yml` to add your documentation to the navigation
+   - Place your entry in the appropriate section under the `nav:` configuration
+   - Follow the existing indentation and format
+
+5. **Test Your Changes**
+   - Set up a local development environment:
+     ```bash
+     python3 -m venv venv
+     source venv/bin/activate
+     pip3 install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin
+     ```
+   - Run the build script to verify your changes:
+     ```bash
+     ./docs/build-all.sh
+     ```
+   - View the documentation locally at `http://127.0.0.1:8000/`
+
+6. **Submit a Pull Request**
+   - Create a new branch for your documentation changes
+   - Commit your changes with a descriptive message
+   - Submit a PR with:
+     - A clear title describing the documentation addition
+     - A detailed description explaining:
+       - The purpose of the new documentation
+       - Why it should be added to the official docs
+       - Any related issues or discussions
+     - Screenshots of the rendered documentation (if applicable)
+
+7. **Review Process**
+   - The HyperBEAM team will review your PR
+   - 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/community/guidelines.md) and [Development Setup](./docs/community/setup.md) documentation.