Skip to content

Latest commit

 

History

History
86 lines (55 loc) · 3.73 KB

README.md

File metadata and controls

86 lines (55 loc) · 3.73 KB
Raw

The Starknet Book

This repository contains the source for The Starknet Book.

Contribution

Every contribution, regardless of its size, plays a pivotal role in refining this work. Together, we advance the Starknet narrative.

  • General Guidelines:
    • Focus on enhancements directly related to the book's content.
    • For typos, errors, or improvements, you don't need a related issue to submit a PR.
    • Review specific areas of interest in the repository issues.

Setup

  1. Rust Packages:
    • Install the cargo toolchain via rustup.
    • Install mdBook and its translation extension:
cargo install mdbook --version 0.4.31 && cargo install mdbook-i18n-helpers --version 0.1.0
  1. Machine Packages:
  • For translations, install gettext: sudo apt install gettext.
  • On Mac, you can use brew install gettext to install.
  1. Repository Operations:
  • Clone the main repository: git clone https://github.com/starknet-edu/starknetbook && cd starknetbook.
  • Create and work on a branch in your fork. If you're unfamiliar, use this guide for assistance.
  • Once done, submit a PR to merge your edits. Ensure you tag a reviewer for feedback (l-henri or @omarespejel).
  1. Formatting
  • Run npm i
  • Then after completing your documentation run npm run format

Understanding the Book's Structure

The Starknet Book is optimized for mdBook:

  • src/SUMMARY.md: The book's structural outline. For adding chapters, modify this document.
  • src/: This directory holds individual chapters. Each is a markdown file, like ch35.md. Use subdirectories for added resources.
  • book.toml: The primary configuration file (regular contributors might not need to adjust this).

Editing Guidelines

Work Locally in English

Ensure all edits to Markdown files are in English.

  • Use mdbook serve to initiate a local server. Access the book at localhost:3000 or append --open to the command to launch a browser automatically: mdbook serve --open.
  • After editing, refresh the browser to see updates. When satisfied, push your changes through a PR.

Translations

Targeting a global readership, this book will undergo translations over time.

  • Initial Version Always in English: Always write files in the src directory in English. This consistency allows for smooth auto-translation.
  • Translation Process:
  • Launch a local server for the intended language, e.g., ./translations.sh es. Without specifying a language, only English translations get extracted.
  • Modify the translation file of interest, like po/es.po. Tools like poedit can be beneficial.
  • Commit changes only in the po/xx.po file. When opening a PR, start with the prefix i18n.

The translation work is inspired from Comprehensive Rust repository.

Initiating a New Translation

For starting translations in a new language:

  • Employ ./translations.sh new xx, replacing xx with your language code. This action generates a language file.
  • For updating the xx.po file, use ./translations.sh xx.
  • Avoid the above command if the xx.po file already exists (which means you are not initiating a new translation).

The Authors