docs: build with mdBook

.github/workflows/CI.yml

@@ -27,3 +27,22 @@ jobs:
  key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
  - run: cargo clippy
  - run: cargo test --all-features
+
+ docs:
+ name: documentation
+ if: ${{ github.event_name == 'push' }}
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Install 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"
+ mkdir mdbook
+ curl -sSL $url | tar -xz --directory=./mdbook
+ echo `pwd`/mdbook >> $GITHUB_PATH
+ - run: mdbook build docs
+ - name: Deploy Production
+ run: netlify deploy --dir=docs/book --site=pretty-yaml --prod
+ env:
+ NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}

.gitignore

@@ -1,2 +1,3 @@
 /target
 dprint_plugin/deployment/plugin.wasm
+docs/book

README.md

@@ -34,7 +34,7 @@ You can also read [dprint CLI documentation](https://dprint.dev/cli/) for using
 
 ## Configuration
 
-Please refer to [Configuration](./docs/config.md).
+Please refer to [Configuration](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md).
 
 ## Using in Rust
 

docs/book.toml

@@ -0,0 +1,8 @@
+[book]
+title = "Pretty YAML Documentation"
+authors = ["Pig Fang"]
+language = "en"
+
+[output.html]
+git-repository-url = "https://github.com/g-plane/pretty_yaml"
+edit-url-template = "https://github.com/g-plane/pretty_yaml/edit/main/docs/{path}"

docs/src/SUMMARY.md

@@ -0,0 +1,16 @@
+# Summary
+
+- [Configuration](./config/README.md)
+ - [printWidth](./config/print-width.md)
+ - [indentWidth](./config/indent-width.md)
+ - [lineBreak](./config/line-break.md)
+ - [quotes](./config/quotes.md)
+ - [trailingComma](./config/trailing-comma.md)
+ - [formatComments](./config/format-comments.md)
+ - [indentBlockSequenceInMap](./config/indent-block-sequence-in-map.md)
+ - [braceSpacing](./config/brace-spacing.md)
+ - [bracketSpacing](./config/bracket-spacing.md)
+ - [dashSpacing](./config/dash-spacing.md)
+ - [trimTrailingWhitespaces](./config/trim-trailing-whitespaces.md)
+ - [trimTrailingZero](./config/trim-trailing-zero.md)
+ - [ignoreCommentDirective](./config/ignore-comment-directive.md)

docs/src/config/README.md

@@ -0,0 +1,4 @@
+# Configuration
+
+Options name in this page are in camel case.
+If you're using Pretty YAML as a Rust crate, please use snake case instead.

docs/src/config/brace-spacing.md

@@ -0,0 +1,17 @@
+# `braceSpacing`
+
+Control whether whitespace should be inserted between braces or not.
+
+Default option is `true`.
+
+## Example for `false`
+
+```yaml
+{a: b}
+```
+
+## Example for `true`
+
+```yaml
+{ a: b }
+```

docs/src/config/bracket-spacing.md

@@ -0,0 +1,17 @@
+# `bracketSpacing`
+
+Control whether whitespace should be inserted between brackets or not.
+
+Default option is `false`.
+
+## Example for `false`
+
+```yaml
+[a, b]
+```
+
+## Example for `true`
+
+```yaml
+[ a, b ]
+```

docs/src/config/dash-spacing.md

@@ -0,0 +1,29 @@
+# `dashSpacing`
+
+Control the whitespace behavior of block compact map in block sequence value.
+This option is only effective when `indentWidth` is greater than 2.
+
+Possible options:
+
+- `"oneSpace"`: Insert only one space after `-`.
+- `"indent"`: Insert spaces to align indentation, respecting `indentWidth` option.
+
+Default option is `"oneSpace"`.
+
+The examples below assume `indentWidth` is `4`.
+
+## Example for `"oneSpace"`
+
+```yaml
+outer:
+ - key1: value1
+ key2: value2
+```
+
+## Example for `"indent"`
+
+```yaml
+outer:
+ - key1: value1
+ key2: value2
+```

docs/src/config/format-comments.md

@@ -0,0 +1,19 @@
+# `formatComments`
+
+Control whether whitespace should be inserted at the beginning of comments or not.
+
+When this option is set to `false`, comments contain leading whitespace will still be kept as-is.
+
+Default option is `false`.
+
+## Example for `false`
+
+```yaml
+#comment
+```
+
+## Example for `true`
+
+```yaml
+# comment
+```

docs/src/config/ignore-comment-directive.md

@@ -0,0 +1,5 @@
+# `ignoreCommentDirective`
+
+Text directive for ignoring formatting specific content.
+
+Default is `"pretty-yaml-ignore"`.

docs/src/config/indent-block-sequence-in-map.md

@@ -0,0 +1,19 @@
+# `indentBlockSequenceInMap`
+
+Control whether block sequence should be indented or not in a block map.
+
+Default option is `true`.
+
+## Example for `false`
+
+```yaml
+key:
+- item
+```
+
+## Example for `true`
+
+```yaml
+key:
+ - item
+```

docs/src/config/indent-width.md

@@ -0,0 +1,5 @@
+# `indentWidth`
+
+Size of indentation.
+
+Default option is `2`. This can't be zero.

docs/src/config/line-break.md

@@ -0,0 +1,5 @@
+# `lineBreak`
+
+Specify use `\n` (LF) or `\r\n` (CRLF) for line break.
+
+Default option is `"lf"`. Possible options are `"lf"` and `"crlf"`.

docs/src/config/print-width.md

@@ -0,0 +1,5 @@
+# `printWidth`
+
+The line width limitation that Pretty YAML should *(but not must)* avoid exceeding. Pretty YAML will try its best to keep line width less than this value, but it may exceed for some cases, for example, a very very long single word.
+
+Default option is `80`.

docs/src/config/quotes.md

@@ -0,0 +1,23 @@
+# `quotes`
+
+Control the quotes.
+
+Possible options:
+
+- `"preferDouble"`: Use double quotes as possible. However if there're escaped characters in strings, quotes will be kept as-is.
+- `"preferSingle"`: Use single quotes as possible. However if there're `\` char or `"` char in strings, quotes will be kept as-is.
+
+Default option is `"preferDouble"`.
+We recommend to use double quotes because behavior in single quoted scalars is counter-intuitive.
+
+## Example for `"preferDouble"`
+
+```yaml
+- "text"
+```
+
+## Example for `"preferSingle"`
+
+```yaml
+- 'text'
+```

docs/src/config/trailing-comma.md

@@ -0,0 +1,27 @@
+# `trailingComma`
+
+Control whether trailing comma should be inserted or not.
+
+Default option is `true`.
+
+## Example for `false`
+
+```yaml
+- [
+ a
+ ]
+- {
+ a: b
+ }
+```
+
+## Example for `true`
+
+```yaml
+- [
+ a,
+ ]
+- {
+ a: b,
+ }
+```

docs/src/config/trim-trailing-whitespaces.md

@@ -0,0 +1,5 @@
+# `trimTrailingWhitespaces`
+
+Control whether trailing whitespaces should be trimmed or not.
+
+Default option is `true`.

docs/src/config/trim-trailing-zero.md

@@ -0,0 +1,21 @@
+# `trimTrailingZero`
+
+Control whether trailing zeros should be removed or not.
+
+Numbers without trailing zeros will still be kept as-is.
+
+Default option is `false`.
+
+## Example for `false`
+
+```yaml
+- 1.20
+- 1.0
+```
+
+## Example for `true`
+
+```yaml
+- 1.2
+- 1
+```

pretty_yaml/README.md

@@ -12,7 +12,7 @@ assert_eq!("- a\n- b\n", &format_text("- a\n- b", &options).unwrap());
 ```
 
 For detailed documentation of configuration,
-please refer to [Configuration](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md) on GitHub.
+please refer to [Configuration](https://pretty-yaml.netlify.app/).
 
 If there're syntax errors in source code, it will return `Err`:
 

pretty_yaml/src/config.rs

@@ -1,4 +1,7 @@
 //! Types about configuration.
+//!
+//! For detailed documentation of configuration,
+//! please read [configuration documentation](https://pretty-yaml.netlify.app/).
 
 #[cfg(feature = "config_serde")]
 use serde::{Deserialize, Serialize};
@@ -7,8 +10,6 @@ use serde::{Deserialize, Serialize};
 #[cfg_attr(feature = "config_serde", derive(Serialize, Deserialize))]
 #[cfg_attr(feature = "config_serde", serde(default))]
 /// The whole configuration of Pretty YAML.
-///
-/// For detail, please refer to [Configuration](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md) on GitHub.
 pub struct FormatOptions {
  #[cfg_attr(feature = "config_serde", serde(flatten))]
  pub layout: LayoutOptions,
@@ -22,18 +23,15 @@ pub struct FormatOptions {
 /// Configuration related to layout, such as indentation or print width.
 pub struct LayoutOptions {
  #[cfg_attr(feature = "config_serde", serde(alias = "printWidth"))]
- /// See [`printWidth`](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md#printwidth) on GitHub
  pub print_width: usize,
 
  #[cfg_attr(feature = "config_serde", serde(alias = "indentWidth"))]
- /// See [`indentWidth`](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md#indentwidth) on GitHub
  pub indent_width: usize,
 
  #[cfg_attr(
  feature = "config_serde",
  serde(alias = "lineBreak", alias = "linebreak")
  )]
- /// See [`lineBreak`](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md#linebreak) on GitHub
  pub line_break: LineBreak,
 }
 
@@ -70,43 +68,33 @@ impl From<LineBreak> for tiny_pretty::LineBreak {
 #[cfg_attr(feature = "config_serde", serde(default))]
 /// Configuration related to syntax.
 pub struct LanguageOptions {
- /// See [`quotes`](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md#quotes) on GitHub
  pub quotes: Quotes,
 
  #[cfg_attr(feature = "config_serde", serde(alias = "trailingComma"))]
- /// See [`trailingComma`](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md#trailingcomma) on GitHub
  pub trailing_comma: bool,
 
  #[cfg_attr(feature = "config_serde", serde(alias = "formatComments"))]
- /// See [`formatComments`](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md#formatcomments) on GitHub
  pub format_comments: bool,
 
  #[cfg_attr(feature = "config_serde", serde(alias = "indentBlockSequenceInMap"))]
- /// See [`indentBlockSequenceInMap`](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md#indentblocksequenceinmap) on GitHub
  pub indent_block_sequence_in_map: bool,
 
  #[cfg_attr(feature = "config_serde", serde(alias = "braceSpacing"))]
- /// See [`braceSpacing`](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md#bracespacing) on GitHub
  pub brace_spacing: bool,
 
  #[cfg_attr(feature = "config_serde", serde(alias = "bracketSpacing"))]
- /// See [`bracketSpacing`](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md#bracketspacing) on GitHub
  pub bracket_spacing: bool,
 
  #[cfg_attr(feature = "config_serde", serde(alias = "dashSpacing"))]
- /// See [`dashSpacing`](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md#dashspacing) on GitHub
  pub dash_spacing: DashSpacing,
 
  #[cfg_attr(feature = "config_serde", serde(alias = "trimTrailingWhitespaces"))]
- /// See [`trimTrailingWhitespaces`](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md#trimtrailingwhitespaces) on GitHub
  pub trim_trailing_whitespaces: bool,
 
  #[cfg_attr(feature = "config_serde", serde(alias = "trimTrailingZero"))]
- /// See [`trimTrailingZero`](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md#trimtrailingzero) on GitHub
  pub trim_trailing_zero: bool,
 
  #[cfg_attr(feature = "config_serde", serde(alias = "ignoreCommentDirective"))]
- /// See [`ignoreCommentDirective`](https://github.com/g-plane/pretty_yaml/blob/main/docs/config.md#ignorecommentdirective) on GitHub
  pub ignore_comment_directive: String,
 }