Add documentation sources

2020-06-09 21:19:59 +09:00 · 2020-06-09 21:19:59 +09:00 · 09685646ae
parent c86effe90f
commit 09685646ae
11 changed files with 277 additions and 0 deletions
--- a/docs/en/docs/getting-started.md
+++ b/docs/en/docs/getting-started.md
@ -0,0 +1,64 @@
+# Getting Started
+
+## Prepare the template file
+
+Create a new directory named `templates` in the same directory as `Cargo.toml`. Copy the following contents and paste it to a new file named `templates/hello.stpl`.
+
+```ejs
+<html>
+  <body>
+    <% for msg in &messages { %>
+      <div><%= msg %></div>
+    <% } %>
+  </body>
+</html>
+```
+
+Now your project structure should be like this:
+
+```text
+Cargo.toml
+src/
+    (Source files)
+templates/
+    hello.stpl
+```
+
+## Render the template
+
+Import the sailfish crates:
+
+```rust
+#[macro_use]
+extern crate sailfish_macros;  // enable derive macros
+
+use sailfish::TemplateOnce;  // import `TemplateOnce` trait
+```
+
+Define the template struct to be rendered:
+
+```rust
+#[derive(TemplateOnce)]  // automatically implement `TemplateOnce` trait
+#[template(path = "hello.stpl")]  // specify the path to template
+struct HelloTemplate<'a> {
+    // data to be passed to the template
+    messages: &'a [String],
+}
+```
+
+And render the data with `render_once()` method.
+
+```rust
+fn main() {
+    let ctx = HelloTemplate {
+        messages: &[String::from("foo"), String::from("bar")];
+    }
+
+    // Now render templates with given data
+    println!("{}", ctx.render_once().unwrap());
+}
+```
+
+That's it!
+
+You can find more examples in the [example](https://github.com/Kogia-sima/sailfish/tree/master/examples) directory in the sailfish repository.
--- a/docs/en/docs/images/favicon.ico
+++ b/docs/en/docs/images/favicon.ico
--- a/docs/en/docs/images/logo.svg
+++ b/docs/en/docs/images/logo.svg
--- a/docs/en/docs/index.md
+++ b/docs/en/docs/index.md
@ -0,0 +1,35 @@
+# Welcome to Sailfish Documentation!
+
+Sailfish is a simple, small, and extremely fast template engine for Rust. This documentation guides you how to get started with sailfish.
+
+This documentation mainly focuses on concepts of the library, general usage, and template syntax. If you've read this documentation and need more specific information, you might want to read the [sailfish API docs](https://docs.rs/sailfish).
+
+Currently the documentation is uncompleted. If you want to improve our documentation, feel free to create a [Pull Request](https://github.com/Kogia-sima/sailfish/pulls) on the repository. I'll be happy if someone contributes to writing documents (English is not my first language and creating a documentation is a hard task for me).
+
+## Why Sailfish ?
+
+There are many libraries for template rendering in Rust. Among those libraries, sailfish aims at **rapid development** and **rapid rendering**. Sailfish has many features that other libraries might not support.
+
+- Write a Rust code directly inside templates, supporting many Rust syntax (struct definision, closure, macro invocation, etc.)
+- Relatively small number of dependencies (<15 crates in total)
+- Extremely fast (See [benchmarks](http://github.com/Kogia-sima/sailfish/blob/master/benches))
+- Better error message
+- Template rendering is always type-safe because templates are statically compiled.
+- Syntax highlighting ([vscode](http://github.com/Kogia-sima/sailfish/blob/master/syntax/vscode), [vim](http://github.com/Kogia-sima/sailfish/blob/master/syntax/vim))
+- Automatically re-compile sources when template file is updated.
+
+## Upcoming features
+
+Since sailfish is on early stage of development, there are many upcoming features that is not supported yet. You can find many [RFC](https://github.com/Kogia-sima/sailfish/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+RFC%22)s in my repository. These RFCs include:
+
+- Dynamic Template Loading
+- Filter
+- `Template` trait (which does not consume itself)
+
+If you have any idea about them or want to implement that feature, please send a comment on the issue!
+
+## License
+
+Copyright &copy; 2020 Ryohei Machida
+
+This project is [MIT](https://github.com/Kogia-sima/sailfish/blob/master/LICENSE) licensed
--- a/docs/en/docs/installation.md
+++ b/docs/en/docs/installation.md
@ -0,0 +1,13 @@
+# Installation
+
+In order to use sailfish templates, you have add two dependencies in your `Cargo.toml`.
+
+```toml
+[dependencies]
+sailfish = "0.0.3"
+sailfish-macros = "0.0.3"
+```
+
+`sailfish` crate contains runtime for rendering contents, and `sailfish-macros` serves you derive macros to compile and import the template files.
+
+These crates are separated so that Rust compiler can compile them independently. This separation makes your compilation faster!
--- a/docs/en/docs/options.md
+++ b/docs/en/docs/options.md
@ -0,0 +1,30 @@
+# Derive Options
+
+You can control the rendering behaviour via `template` attribute.
+
+```rust
+#[derive(TemplateOnce)]
+#[template(path = "template.stpl", escape = false)]
+struct TemplateStruct {
+    ...
+}
+```
+
+`template` attribute accepts the following options.
+
+- `path`: path to template file. This options is always required.
+- `escape`: Enable HTML escaping (default: `false`)
+- `delimiter`: Replace the '%' character used for the tag delimiter (default: '%')
+- `rm_whitespace`: try to strip whitespaces as much as possible without collapsing HTML structure (default: `false`). This option might not work correctly if your templates have inline `script` tag.
+
+You can split the options into multiple `template` attributes.
+
+```rust
+#[derive(TemplateOnce)]
+#[template(path = "template.stpl")]
+#[template(delimiter = '?')]
+#[template(rm_whitespace = true)]
+struct TemplateStruct {
+    ...
+}
+```
--- a/docs/en/docs/syntax/overview.md
+++ b/docs/en/docs/syntax/overview.md
@ -0,0 +1,37 @@
+# Template Syntax Overview
+
+## Tags
+
+- `<% %>`: Inline tag, you can write Rust code inside this tag
+- `<%= %>`: Evaluate the Rust expression and outputs the value into the template (HTML escaped)
+- `<%- %>`: Evaluate the Rust expression and outputs the unescaped value into the template
+- `<%# %>`: Comment tag
+- `<%%`: Outputs a literal '<%'
+
+## Condition
+
+```ejs
+<% if messages.is_empty() { %>
+  <div>No messages</div>
+<% } %>
+```
+
+## loop
+
+```ejs
+<% for (i, msg) in messages.iter().enumerate() { %>
+  <div><%= i %>: <%= msg %></div>
+<% } %>
+```
+
+## Includes
+
+```ejs
+<% include!("path/to/template"); %>
+```
+
+Unlike EJS, you cannot omit the file extension.
+
+## Helpers
+
+(Work in progress)
--- a/docs/en/mkdocs.yml
+++ b/docs/en/mkdocs.yml
@ -0,0 +1,49 @@
+# Project information
+site_name: 'Sailfish Documentation'
+# site_description: 'Sailfish Documentation'
+site_author: 'Ryohei Machida'
+# site_url: 'https://***.com'
+
+# Copyright
+copyright: '&copy; 2020 Ryohei Machida'
+
+# Repository
+repo_name: 'Kogia-sima/sailfish'
+repo_url: 'https://github.com/Kogia-sima/sailfish'
+
+# Configuration
+theme:
+  name: 'material'
+  language: 'en'
+  logo: 'images/logo.svg'
+  palette:
+    scheme: 'default'
+    primary: 'deep purple'
+    accent: 'deep purple'
+  favicon: 'images/favicon.ico'
+  font:
+    text: 'Ubuntu'
+    code: 'Ubuntu Mono'
+
+# Extensions
+markdown_extensions:
+  - codehilite
+  - footnotes
+
+# Customization
+# extra_css:
+#   - 'assets/css/custom.css'
+
+extra:
+  social:
+    - icon: 'fontawesome/brands/github-alt'
+      link: 'https://github.com/Kogia-sima'
+
+# Page tree
+nav:
+  - 'Welcome': 'index.md'
+  - 'Installation': 'installation.md'
+  - 'Getting Started': 'getting-started.md'
+  - 'Options': 'options.md'
+  - 'Syntax':
+    - 'Overview': 'syntax/overview.md'
--- a/netlify.toml
+++ b/netlify.toml
@ -0,0 +1,7 @@
+[build]
+command = "python3 scripts/build-docs.py"
+publish = "site"
+
+[[redirects]]
+  from = "/*"
+  to = "/en/:splat"
--- a/requirements.txt
+++ b/requirements.txt
@ -0,0 +1,2 @@
+mkdocs-material==5.2.3
+mkdocs==1.1.2
--- a/runtime.txt
+++ b/runtime.txt
@ -0,0 +1 @@
+3.6