Merge remote-tracking branch 'origin/main'

.github/workflows/install-mdbook/action.yml

@@ -0,0 +1,15 @@
+name: Install mdbook and dependencies
+
+description: Install mdbook with the dependencies we need.
+
+runs:
+  using: composite
+  steps:
+    # The --locked flag is important for reproducible builds.
+    - name: Install mdbook
+      run: cargo install mdbook --locked --version 0.4.31
+      shell: bash
+
+    - name: Install mdbook-i18n-helpers
+      run: cargo install mdbook-i18n-helpers --locked --version 0.1.0
+      shell: bash

.github/workflows/mdbook.yml

@@ -0,0 +1,72 @@
+# Sample workflow for building and deploying a mdBook site to GitHub Pages
+#
+# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
+#
+name: Deploy mdBook site to Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  publish:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Rust cache
+        uses: ./.github/workflows/setup-rust-cache
+
+      - name: Install mdbook
+        uses: ./.github/workflows/install-mdbook
+
+      - name: Build in English
+        run: |
+          mdbook build -d book
+
+      - name: Build all translations
+        run: |
+          for po_lang in $(cat ./LANGUAGES); do
+              echo "::group::Building $po_lang translation"
+              MDBOOK_BOOK__LANGUAGE=$po_lang \
+              mdbook build -d book/$po_lang
+              echo "::endgroup::"
+          done
+
+      # - name: Setup Pages
+      #   uses: actions/configure-pages@v3
+
+      # - name: Upload artifact
+      #   uses: actions/upload-pages-artifact@v1
+      #   with:
+      #     path: ./book
+
+      # - name: Deploy to GitHub Pages
+      #   id: deployment
+      #   uses: actions/deploy-pages@v2
+
+      - name: Rename book to public_html
+        run: mv book public_html
+
+      - name: scp upload to production site
+        run: |
+          sshpass -p ${{ secrets.PROD_PASS }} scp -o 'StrictHostKeyChecking no' -r public_html/ ${{ secrets.PROD_USER }}@${{ secrets.PROD_IP }}:~/

.github/workflows/setup-rust-cache/action.yml

@@ -0,0 +1,9 @@
+name: Setup Rust cache
+
+description: Configure the rust-cache workflow.
+
+runs:
+  using: composite
+  steps:
+    - name: Setup Rust cache
+      uses: Swatinem/rust-cache@v2

.gitignore

@@ -6,4 +6,4 @@ node_modules
 # Editors tmp files.
 *~
 .idea/
-
+.vscode

.prettierignore

@@ -0,0 +1 @@
+theme

LANGUAGES

@@ -0,0 +1 @@
+es

README.md

@@ -10,29 +10,45 @@ We value and welcome all contributions!
 - Prioritize contributions that directly pertain to the book's content.
 - Even if an issue doesn't exist, feel free to create a PR for typos, errors, or content improvements and additions.
 
-## Building the Book
+### Setup
 
-Before building or contributing to the book:
+1. Rust related packages:
+   - Install toolchain providing `cargo` using [rustup](https://rustup.rs/).
+   - Install [mdBook](https://rust-lang.github.io/mdBook/guide/installation.html) and the translation extension:
+   ```
+   cargo install mdbook --version 0.4.31 mdbook-i18n-helpers --version 0.1.0
+   ```
+2. Host machine packages:
+   - Install [gettext](https://www.gnu.org/software/gettext/) for translations, usually available with regular package manager:
+     `sudo apt install gettext`.
+3. Clone this repository.
 
-- Ensure you have [mdBook] installed. While version 0.4.31 is recommended, newer versions should be compatible.
+### Work locally (english, main language)
 
-```bash
-$ cargo install mdbook --version 0.4.31
-```
+All the Markdown files **MUST** be edited in english. To work locally in english:
 
-Follow these steps to build and view the book:
+- Start a local server with `mdbook serve` and visit [localhost:3000](http://localhost:3000) to view the book.
+  You can use the `--open` flag to open the browser automatically: `mdbook serve --open`.
+- Make changes to the book and refresh the browser to see the changes.
+- Open a PR with your changes.
 
-1. Build the book:
+### Work locally (translations)
 
-```bash
-$ mdbook build
-```
+This book is targetting international audience, and aims at being gradually translated in several languages.
+**All files in the `src` directory MUST be written in english**. This ensures that all the translation files can be
+auto-generated and updated by translators.
+To work with translations, those are the steps to update the translated content:
 
-2. After building, the compiled content will be located in the **`book`** subdirectory.
-3. To view the content in a browser:
+- Run a local server for the language you want to edit: `./translations.sh es` for instance. If no language is provided, the script will only extract translations from english.
+- Open the translation file you are interested in `po/es.po` for instance. You can also use editors like [poedit](https://poedit.net/) to help you on this task.
+- When you are done, you should only have changes into the `po/xx.po` file. Commit them and open a PR.
+  The PR must stars with `i18n` to let the maintainers know that the PR is only changing translation.
+  The translation work is inspired from [Comprehensive Rust repository](https://github.com/google/comprehensive-rust/blob/main/TRANSLATIONS.md).
 
-```bash
-$ mdbook serve --open
-```
+#### Initiate a new translation for your language
 
-Tip: After making edits, simply refresh your browser to see the updates.
+If you wish to initiate a new translation for your language without running a local server, consider the following tips:
+
+- Execute the command `./translations.sh new xx` (replace `xx` with your language code). This method can generate the `xx.po` file of your language for you.
+- To update your `xx.po` file, execute the command `./translations.sh xx` (replace `xx` with your language code), as mentioned in the previous chapter.
+- If the `xx.po` file already exists (which means you are not initiating a new translation), you should not run this command.

book.toml

@@ -1,4 +1,15 @@
 [book]
 authors = ["Starknet Community with support from Starkware and the Starknet Foundation"]
+language = "en"
+multilingual = false
 src = "src"
 title = "The Starknet Book"
+
+[build]
+extra-watch-dirs = ["po"]
+
+[preprocessor.gettext]
+after = ["links"]
+
+[output.html]
+git-repository-url = "https://github.com/starknet-edu/starknetbook"