Create documentation website

.github/workflows/book.yaml

@@ -0,0 +1,29 @@
+name: Deploy documentation
+
+on:
+  push:
+    branches:
+      - main
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v2
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: 'latest'
+
+      - name: Build book
+        run: mdbook build ./book
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book/output

.gitignore

@@ -1,3 +1,5 @@
 /target
+/.vscode
+/book/output
+
 Cargo.lock
-.vscode/settings.json

book/book.toml

@@ -0,0 +1,12 @@
+[book]
+title = "Rosetta Documentation"
+authors = ["baptiste0928"]
+language = "en"
+src = "src"
+
+[build]
+build-dir = "output"
+
+[output.html]
+git-repository-url = "https://github.com/baptiste0928/rosetta"
+edit-url-template = "https://github.com/baptiste0928/rosetta/edit/main/book/{path}"

book/src/SUMMARY.md

@@ -0,0 +1,13 @@
+# Summary
+
+- [Overview](./overview.md)
+- [Getting started](./getting_started.md)
+- [Optional features](./optional_features.md)
+
+# Reference
+- [Build options](./reference/build_options.md)
+- [JSON file format](./reference/json_format.md)
+
+# Usage tips
+- [VS Code extensions](./tips/extensions.md)
+

book/src/getting_started.md

@@ -0,0 +1,80 @@
+# Getting started
+
+The following guide explains how to use `rosetta-i18` and `rosetta-build` to manage your translations.
+Please refer to other sections in this documentation or to the API documentation for in depth explanations.
+
+## Installation
+Rosetta is separated into two crates: `rosetta-i18n` and `rosetta-build`. To install both, add the following to your `Cargo.toml`:
+
+```toml
+[dependencies]
+rosetta-i18n = "0.1"
+
+[build-dependencies]
+rosetta-build = "0.1"
+```
+
+`rosetta-build` is used inside a build script and must be a build dependency.
+
+## Writing translations files
+Rosetta use JSON translation files, which is similar to the one used by many other translation libraries and this widely supported.
+We need to put these files somewhere, for example in a `/locales` directory.
+
+`locales/en.json`
+```json
+{
+    "hello": "Hello world!",
+    "hello_name": "Hello {name}!"
+}
+```
+
+In this example, we defined two keys, `hello` and `hello_name`. The first is a static string, whereas the second contains the `name` variable which will be
+replaced at runtime by the value of your choice.
+
+Create a file for each language you want to be supported by your application. It is not required that all files contain all keys: we will define the fallback language later.
+
+## Generating code from translation files
+It is now that the magic happens. Rosetta lets you generate a Rust type from your translation files.
+For that, it use a [build script](https://doc.rust-lang.org/cargo/reference/build-scripts.html) which will be run each time you edit a translation file.
+
+We need to create a `build.rs` file at the root folder of the crate (same folder as the `Cargo.toml` file).
+
+`build.rs`
+```rust
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    rosetta_build::config()
+        .source("en", "locales/en.json")
+        .source("fr", "locales/fr.json")
+        .fallback("en")
+        .generate()?;
+
+    Ok(())
+}
+```
+
+This script use the `rosetta_build` crate. In this example, we define two languages with [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1)
+language identifiers: `en` and `fr`. The `en` language is defined as fallback and will be used if a key is not defined in other languages.
+
+The `.generate()` method is responsible for code generation. By default, the output file will be generated in a folder inside the `target` directory (`OUT_DIR` env variable). 
+
+## Using the generated type
+The generated type (named `Lang` except if you defined another name - see the previous section) must be included in your code with the `include_translations`
+macro. A good practice is to isolate it in a dedicated module.
+
+Each translation key is transformed into a method, and each language into an enum variant. Parameters are sorted alphabetically to avoid silent breaking changes
+when reordering.
+
+`src/main.rs`
+```rust
+mod translations {
+    rosetta_i18n::include_translations!();
+}
+
+fn main() {
+    use translations::Lang;
+
+    println!("{}", Lang::En.hello());  // Hello world!
+    println!("{}", Lang::En.hello_name("Rust"));  // Hello Rust!
+}
+```
+

book/src/optional_features.md

@@ -0,0 +1,19 @@
+# Optional features
+
+The `rosetta-i18n` and `rosetta-build` crates allow to turn on some additional features with [Cargo features](https://doc.rust-lang.org/cargo/reference/features.html).
+Most of these requires additional dependencies and are not enabled by default.
+
+> To enable a feature, you need to add a `feature` key in the `Cargo.toml` file like the following example:
+>
+> ```toml
+> rosetta-i18n = { version = "0.1", features = ["serde"] }
+> ``` 
+
+## `rosetta-i18n`
+
+- `serde`: enable [Serde](https://serde.rs/) support, providing `Serialize` and `Deserialize` implementation for some types. Utility functions to serialize and deserialize
+generated types are also provided.
+
+## `rosetta-build`
+
+- `rustfmt` *(enabled by default)*: format generated code with [rustfmt](https://github.com/rust-lang/rustfmt). Disable this feature if `rustfmt` is not installed in your computer.

book/src/overview.md

@@ -0,0 +1,40 @@
+# Overview
+
+Rosetta is an easy-to-use Rust [internationalization](https://en.wikipedia.org/wiki/Internationalization_and_localization)
+library powered by code generation. Unlike other libraries, translation files are parsed and embedded into the
+resulting binary at build-time. This provide a better developer experience and reduce runtime overheat.
+
+
+Using your translation files in your project is (almost) as easy as that:
+```rust
+rosetta_i18n::include_translations!();
+
+println!("{}", Lang::En.hello("world"));  // Hello, world!
+```
+
+The following documentation aims to provide an exhaustive guide about using Rosetta in your project.
+See [Getting started](./getting_started.md) to get an usage overview.
+
+## Related links
+Here are all the links related to the project:
+
+- **[GitHub repository](https://github.com/baptiste0928/rosetta)** - where the development happen, feel free to contribute!
+- [`rosetta-i18n` on crates.io](https://crates.io/crates/rosetta-i18n) - main crate containing all useful runtime features.
+- [`rosetta-build` on crates.io](https://crates.io/crates/rosetta-build) - crate used for code generation.
+- [`rosetta-i18n`](https://docs.rs/rosetta-i18n/) and [`rosetta-build`](https://docs.rs/rosetta-build/) on **docs.rs** - up-to-date API documentation.
+
+> Please give a ⭐ to the GitHub repository if you use Rosetta.
+
+## Support
+If you encounter bugs or need help using Rosetta, here's what to do:
+
+- **If you need help with Rosetta**, [open a new discussion](https://github.com/baptiste0928/rosetta/discussions) on the GitHub repository.
+- **To report a bug or suggest a new feature**, [open a new issue](https://github.com/baptiste0928/rosetta/issues) on the GitHub repository.
+
+Please do not open issues for help request, this is not the right place for it. Use discussions instead.
+
+## Contributing
+Rosetta is free and open-source. You can find the source code on GitHub and open a new issue to report bug or request features.
+If you want to improve the code or the documentation, consider opening a [pull request](https://github.com/baptiste0928/rosetta/pulls).
+
+Any contribution is welcome, even the smallest! 🙌

book/src/reference/build_options.md

@@ -0,0 +1,15 @@
+# Build options
+
+The following is an exhaustive reference of all configurable build options.
+
+These options are provided as methods of the [`RosettaBuilder`](https://docs.rs/rosetta-build/*/rosetta_build/struct.RosettaBuilder.html) type.
+
+**Required options :**
+- [`.fallback()`](https://docs.rs/rosetta-build/*/rosetta_build/struct.RosettaBuilder.html#method.fallback): register the fallback language with a given language identifier and path
+- [`.source()`](https://docs.rs/rosetta-build/*/rosetta_build/struct.RosettaBuilder.html#method.source): register an additional translation source with a given language identifier and path
+
+**Additional options :**
+- [`.name()`](https://docs.rs/rosetta-build/*/rosetta_build/struct.RosettaBuilder.html#method.name): use a custom name for the generate type (`Lang` by default)
+- [`.output()`](https://docs.rs/rosetta-build/*/rosetta_build/struct.RosettaBuilder.html#method.output): export the type in another output location (`OUT_DIR` by default)
+
+More information in the [`RosettaBuilder` API documentation](https://docs.rs/rosetta-build/*/rosetta_build/struct.RosettaBuilder.html).

book/src/reference/json_format.md

@@ -0,0 +1,26 @@
+# JSON file format
+
+The following is an exhaustive reference of the [JSON](https://en.wikipedia.org/wiki/JSON) file format used for translations.
+
+> **Note:** nested keys are not yet available.
+
+## Simple key
+A simple translation key is a static string key without any variable interpolation. The `{` and `}` characters are not allowed.
+
+```json
+{
+    "simple": "Hello world!"
+}
+```
+
+## String formatting
+You can add variables inside keys to insert dynamic content at runtime. Variable name should be in `snake_case` surrounded by `{` and `}` characters.
+
+```json
+{
+    "formatted": "I like three things: {first}, {second} and Rust."
+}
+```
+
+You can add as many parameters as you want. The same parameter can be inserted several times.
+Languages that are not fallback languages **must** have the same parameters as the fallback language.

book/src/tips/extensions.md

@@ -0,0 +1,36 @@
+# Useful extensions
+
+If you are using [Visual Studio Code](https://code.visualstudio.com/), here is some useful extensions you can use.
+
+## Using with Rust Analyzer
+[rust-analyzer](https://rust-analyzer.github.io/) is a popular extension providing completion and more for Rust files.
+If the generated code is not correctly loaded, add the following line to the `.vscode/settings.json` file:
+
+```json
+"rust-analyzer.cargo.loadOutDirsFromCheck": true
+```
+
+## Using with i18n ally
+[i18n ally](https://github.com/lokalise/i18n-ally) is an all-in-one i18n extension for VS Code that provide inline annotation of translated strings in your code.
+
+![i18n ally example usage](./i18n-ally.png)
+
+*i18n ally* supports [custom translations frameworks](https://github.com/lokalise/i18n-ally/wiki/Custom-Framework) by adding a simple config file.
+Because code generated by Rosetta looks like any Rust method, the following configuration will consider that any method of a variable named `lang`
+or an enum named `Lang` is a translation key. It's not perfect as trait methods are also considered by the extension as translations keys, but it
+work well in most case.
+
+Create a `.vscode/i18n-ally-custom-framework.yml` file with the following content to enable Rosetta support. Edit this configuration if you are not
+using `lang` as variable name.
+```yaml
+# .vscode/i18n-ally-custom-framework.yml
+languageIds:
+  - rust
+
+usageMatchRegex:
+  - "[^\\w\\d]Lang::[A-z]+\\.([a-z_]+)\\(.*\\)"
+  - "[^\\w\\d]lang\\.([a-z_]+)\\(.*\\)"
+
+# If set to true, only enables this custom framework (will disable all built-in frameworks)
+monopoly: true
+```