docs: add mdbook readme and common CI to release mdbooks (#182)

.github/workflows/deploy-docs.yaml

@@ -1,18 +1,26 @@
-name: Deploy docs to GH pages
+name: Deploy docs
 
 on:
   push:
-    branches: ["main"]
+    branches:
+      - "main"
+    tags:
+      - "*.*.*"
     paths:
       - 'docs/**'
       - '.github/workflows/deploy-docs.yaml'
   workflow_dispatch:
-
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-  contents: read
-  pages: write
-  id-token: write
+    inputs:
+      version:
+        type: string
+        description: "Version of the documentation to deploy"
+        required: false
+        default: "latest"
+      docs-dir:
+        type: string
+        description: "Directory with the documentation"
+        required: false
+        default: "docs"
 
 # 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 production deployments to complete.
@@ -21,36 +29,20 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+
+  deploy-docs:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Install latest mdbook
-        run: |
-          TAG=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
-          URL="https://github.com/rust-lang/mdbook/releases/download/${TAG}/mdbook-${TAG}-x86_64-unknown-linux-gnu.tar.gz"
-          MDBOOK_DIR=mdbook
-          mkdir -p "${MDBOOK_DIR}"
-          curl -sSL ${URL} | tar -xz --directory=${MDBOOK_DIR}
-          echo "${PWD}/mdbook" >> "${GITHUB_PATH}"
-
-      - name: Build Book
-        working-directory: docs
-        run: mdbook build
-
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+      - name: Deploy
+        uses: matter-labs/deploy-mdbooks@v1
         with:
-          path: 'docs/book'
-
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+          version: ${{ inputs.version || github.ref_name }}
+          docs-dir: ${{ inputs.docs-dir || 'docs' }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          force-orphan: true
+          enable-tests: true

README.md

@@ -24,6 +24,11 @@ To run the unit and CLI tests, execute the following command from the repository
 cargo test
 ```
 
+## Documentation
+
+Documentation is using [mdBook](https://github.com/rust-lang/mdBook) utility and is available in the `docs/` directory.
+To build the documentation, follow the [instructions](./docs/README.md).
+
 ## Troubleshooting
 
 If you have multiple LLVM builds in your system, ensure that you choose the correct one to build the compiler.

docs/README.md

@@ -0,0 +1,57 @@
+# ZKsync Solidity Compiler Toolchain Documentation
+
+This directory contains an `mdBook` project for ZKsync Solidity Compiler Toolchain documentation.
+This README will guide you on how to build and test the book locally.
+
+## Prerequisites
+
+Before you begin, ensure you have the `mdbook` installed:
+
+  ```bash
+  cargo install mdbook
+  ```
+
+## Build the Book
+
+To build the book, use the following command:
+
+```bash
+mdbook build
+```
+
+This command generates the static HTML files in the `book/` directory. You can open `book/index.html` in your browser to view the generated book.
+
+## Serve the Book Locally
+
+For easier development and to preview changes as you edit, you can serve the book locally with:
+
+```bash
+mdbook serve
+```
+
+This will start a local web server and open the book in your default browser. Any changes made to the markdown files will automatically reload the book.
+
+By default, the book will be accessible at: `http://localhost:3000`.
+
+## Testing the Book
+
+To ensure your book is correctly built and formatted, you can use the built-in `mdBook` linter by running:
+
+```bash
+mdbook test
+```
+
+This will check for common issues such as broken links or missing files.
+
+## Directory Structure
+
+- `src/`: This directory contains all the markdown files for the chapters.
+- `book/`: This is the output directory where the built HTML files are generated.
+- `book.toml`: Configuration file for the `mdBook`.
+
+## Deployment
+
+The book is automatically deployed each time a commit is pushed to the `main` branch or a new release tag is created.
+The generated HTML files are hosted on GitHub Pages and are accessible at:
+* https://matter-labs.github.io/era-compiler-solidity/latest/ for the latest documentation.
+* https://matter-labs.github.io/era-compiler-solidity/vX.Y.Z/ for the specific version documentation.