docs lint style (#78)

* docs: update demo gif to demo2 * style: lint errors and other style fixes - line length - code block languages (console->shell, plain, etc) - heading level (H2 comes after H1 etc.) - indent code blocks within lists
ratatui · Sep 18, 2023 · 1a8cfd8 · 1a8cfd8
1 parent 90c813e
commit 1a8cfd8
Show file tree

Hide file tree

Showing 28 changed files with 196 additions and 175 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -11,3 +11,6 @@ charset = utf-8
 trim_trailing_whitespace = false
 insert_final_newline = true
 max_line_length = 100
+
+[.yml]
+indent_size = 2
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
@@ -3,10 +3,15 @@
 single-h1: false
 line-length:
     line_length: 100
+    code_blocks: false # we have some blocks that show the output of commands that are long
 
 # SUMMARY.md uses empty links to show table of contents items that are not yet implemented
 no-empty-links: false
 
 no-inline-html:
     allowed_elements:
         - img # we display the logo using an img tag, so it can be floated beside the text
+        - iframe # for youtube vids
+        - div # for example output
+        - p # for example output
+        - span # for example output
diff --git a/src/LICENSE.md b/src/LICENSE.md
@@ -1 +1,3 @@
+# LICENSE
+
 {{#include ../LICENSE.md}}
diff --git a/src/README.md b/src/README.md
@@ -1,6 +1,6 @@
 # Introduction
 
-![](https://user-images.githubusercontent.com/24392180/244943746-93ab0e38-93e0-4ae0-a31b-91ae6c393185.gif)
+![Demo](https://raw.githubusercontent.com/ratatui-org/ratatui/images/examples/demo2-noborders.gif)
 
 ## What is ratatui?
 

diff --git a/src/concepts/event_handling.md b/src/concepts/event_handling.md
@@ -7,7 +7,7 @@ However, there are a few ways to think about event handling that may help you. W
 exhaustive list, it covers a few of the more common implementations. But remember, the correct way,
 is the one that works for you and your current application.
 
-### Centralized event handling
+## Centralized event handling
 
 This is the simplest way to handle events because it handles all of the events as they appear. It is
 often simply a match on the results of `event::read()?` (in crossterm) on the different supported
@@ -18,7 +18,7 @@ Cons: However, this particular way of handling events simply does not scale well
 events are handled in one place, you will be unable to split different groups of keybinds out into
 separate locations.
 
-### Centralized catching, message passing
+## Centralized catching, message passing
 
 This way of handling events involves polling for events in one place, and then sending
 messages/calling sub functions with the event that was caught. Pros: This has a similar appeal to
@@ -30,7 +30,7 @@ messages.
 Cons: This method requires a main loop to be running to consistently poll for events in a
 centralized place.
 
-### Distributed event loops/segmented applications
+## Distributed event loops/segmented applications
 
 In this style, control of the `Terminal` and the main loop to a sub-module. In this case, the entire
 rendering and event handling responsibilities can be safely passed to the sub-module. In theory, an

diff --git a/src/concepts/rendering.md b/src/concepts/rendering.md
@@ -37,11 +37,17 @@ loop {
 [This article](https://caseymuratori.com/blog_0001) and the accompanying YouTube video is worth your
 time if you are new to the immediate mode rendering paradigm.
 
-<iframe width="560" height="315" src="https://www.youtube.com/embed/Z1qyvQsjK5Y?si=eiBHXiXIo3Z0u2zs" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+<iframe width="560" height="315" src="https://www.youtube.com/embed/Z1qyvQsjK5Y?si=eiBHXiXIo3Z0u2zs"
+ title="YouTube video player" frameborder="0"
+ allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+ allowfullscreen></iframe>
 
 This 4 minute talk about `IMGUI` is also tangentially relevant.
 
-<iframe width="560" height="315" src="https://www.youtube.com/embed/LSRJ1jZq90k?si=8NB5yiZ8IGS_QE_E" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+<iframe width="560" height="315" src="https://www.youtube.com/embed/LSRJ1jZq90k?si=8NB5yiZ8IGS_QE_E"
+ title="YouTube video player" frameborder="0"
+ allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+ allowfullscreen></iframe>
 
 ## Advantages of Immediate Mode Rendering
 
@@ -58,7 +64,8 @@ This 4 minute talk about `IMGUI` is also tangentially relevant.
 
   ```admonish note
   The `ratatui` library in particular only handles how widget would be rendered to a "Backend", e.g.
-  `crossterm`. The `Backend` in question would use an external crate e.g. `crossterm` for actually drawing to the terminal.
+  `crossterm`. The `Backend` in question would use an external crate e.g. `crossterm` for actually
+  drawing to the terminal.
   ```
 
 - **Event loop orchestration**: Along with managing "the render loop", developers are also

diff --git a/src/developer-guide/book.md b/src/developer-guide/book.md
@@ -22,7 +22,7 @@ cargo install mdbook-emojicodes --version 0.2.2
 
 These plugins allow additional features.
 
-### `mdbook-admonish`
+## `mdbook-admonish`
 
 The following raw markdown:
 
@@ -62,7 +62,7 @@ This is a warning
 This is a info
 ```
 
-### `mdbook-mermaid`
+## `mdbook-mermaid`
 
 The following raw markdown:
 
@@ -86,7 +86,7 @@ graph TD;
     C-->D;
 ```
 
-### `mdbook-svgbob2`
+## `mdbook-svgbob2`
 
 The following raw markdown:
 
@@ -114,7 +114,7 @@ will render as the following:
        '
 ```
 
-### `mdbook-emojicodes`
+## `mdbook-emojicodes`
 
 The following raw markdown:
 

diff --git a/src/developer-guide/ratatui.md b/src/developer-guide/ratatui.md
@@ -3,7 +3,7 @@
 Check out the [CONTRIBUTING GUIDE](https://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md)
 for more information.
 
-### Keep PRs small, intentional and focused
+## Keep PRs small, intentional and focused
 
 Try to do one pull request per change. The time taken to review a PR grows exponential with the size
 of the change. Small focused PRs will generally be much more faster to review. PRs that include both
@@ -12,15 +12,15 @@ change becomes a place where a bug may have been introduced. Consider splitting
 reformatting changes into a separate PR from those that make a behavioral change, as the tests help
 guarantee that the behavior is unchanged.
 
-### Search `tui-rs` for similar work
+## Search `tui-rs` for similar work
 
 The original fork of Ratatui, [`tui-rs`](https://github.com/fdehau/tui-rs/), has a large amount of
 history of the project. Please search, read, link, and summarize any relevant
 [issues](https://github.com/fdehau/tui-rs/issues/),
 [discussions](https://github.com/fdehau/tui-rs/discussions/) and
 [pull requests](https://github.com/fdehau/tui-rs/pulls).
 
-### Use conventional commits
+## Use conventional commits
 
 We use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) and check for them as
 a lint build step. To help adhere to the format, we recommend to install
@@ -32,7 +32,7 @@ describes the nature of the problem that the commit is solving and any unintuiti
 change. It's rare that code changes can easily communicate intent, so make sure this is clearly
 documented.
 
-### Clean up your commits
+## Clean up your commits
 
 The final version of your PR that will be committed to the repository should be rebased and tested
 against main. Every commit will end up as a line in the changelog, so please squash commits that are
@@ -41,22 +41,22 @@ commit (unless there is a strong reason to stack the commits). See
 [Git Best Practices - On Sausage Making](https://sethrobertson.github.io/GitBestPractices/#sausage)
 for more on this.
 
-### Run CI tests before pushing a PR
+## Run CI tests before pushing a PR
 
 We're using [cargo-husky](https://github.com/rhysd/cargo-husky) to automatically run git hooks,
 which will run `cargo make ci` before each push. To initialize the hook run `cargo test`. If
 `cargo-make` is not installed, it will provide instructions to install it for you. This will ensure
 that your code is formatted, compiles and passes all tests before you push. If you need to skip this
 check, you can use `git push --no-verify`.
 
-### Sign your commits
+## Sign your commits
 
 We use commit signature verification, which will block commits from being merged via the UI unless
 they are signed. To set up your machine to sign commits, see
 [managing commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification)
 in GitHub docs.
 
-### Setup
+## Setup
 
 Clone the repo and build it using [cargo-make](https://sagiegurari.github.io/cargo-make/)
 
@@ -71,7 +71,7 @@ cd ratatui
 cargo make build
 ```
 
-### Tests
+## Tests
 
 The [test coverage](https://app.codecov.io/gh/ratatui-org/ratatui) of the crate is reasonably good,
 but this can always be improved. Focus on keeping the tests simple and obvious and write unit tests
@@ -95,7 +95,7 @@ exist to show coverage directly in your editor. E.g.:
 - <https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters>
 - <https://github.com/alepez/vim-llvmcov>
 
-### Use of unsafe for optimization purposes
+## Use of unsafe for optimization purposes
 
 We don't currently use any unsafe code in Ratatui, and would like to keep it that way. However there
 may be specific cases that this becomes necessary in order to avoid slowness. Please see

diff --git a/src/highlights/v0.21.md b/src/highlights/v0.21.md
@@ -1,6 +1,6 @@
 # [v0.21](https://github.com/ratatui-org/ratatui/releases/tag/v0.21.0)
 
-### New backend: `termwiz`
+## New backend: `termwiz`
 
 `ratatui` supports a new backend called `termwiz` which is a "Terminal Wizardry" crate that powers
 [wezterm](https://github.com/wez/wezterm).
@@ -44,7 +44,7 @@ fn main() -> Result<(), Box<dyn Error>> {
 
 ---
 
-### New widget: Calendar
+## New widget: Calendar
 
 A calendar widget has been added which was originally a part of the
 [extra-widgets](https://github.com/sophacles/extra-widgets) repository.
@@ -72,7 +72,7 @@ Monthly::new(
 
 Results in:
 
-```sh
+```plain
      January 2023
  Su Mo Tu We Th Fr Sa
   1  2  3  4  5  6  7
@@ -84,7 +84,7 @@ Results in:
 
 ---
 
-### New widget: Circle
+## New widget: Circle
 
 `Circle` widget has been added with the use-case of showing an accuracy radius on the world map.
 
@@ -107,15 +107,15 @@ Canvas::default()
 
 Results in:
 
-```sh
+```plain
  ⡠⠤⢤⡀
 ⢸⡁  ⡧
  ⠑⠒⠚⠁
 ```
 
 ---
 
-### Inline Viewport
+## Inline Viewport
 
 This was a highly requested feature and the original implementation was done by
 [@fdehau](https://github.com/fdehau) himself. Folks at [Atuin](https://atuin.sh) completed the
@@ -129,7 +129,7 @@ In the repository, there is an example that simulates downloading multiple files
 
 ---
 
-### Block: title on bottom
+## Block: title on bottom
 
 > Before you could only put the title on the top row of a Block. Now you can put it on the bottom
 > row! Revolutionary.
@@ -150,7 +150,7 @@ Paragraph::new("ratatui")
 
 Results in:
 
-```sh
+```plain
 ┌─────────────────────┐
 │       ratatui       │
 │                     │
@@ -159,7 +159,7 @@ Results in:
 
 ---
 
-### Block: support adding padding
+## Block: support adding padding
 
 If we want to render a widget inside a `Block` with a certain distance from its borders, we need to
 create another `Layout` element based on the outer `Block`, add a margin and render the `Widget`
@@ -195,7 +195,7 @@ f.render_widget(paragraph, area);
 
 ---
 
-### Text: display secure data
+## Text: display secure data
 
 A new type called `Masked` is added for text-related types for masking data with a mask character.
 The example usage is as follows:
@@ -212,13 +212,13 @@ Line::from(vec![
 
 Results in:
 
-```sh
+```plain
 Masked text: ********
 ```
 
 ---
 
-### `border!` macro
+## `border!` macro
 
 A `border!` macro has been added that takes `TOP`, `BOTTOM`, `LEFT`, `RIGHT`, and `ALL` and returns
 a `Borders` object.
@@ -246,7 +246,7 @@ Going forward, we will most likely put the new macros behind `macros` feature as
 
 ---
 
-### Color: support conversion from `String`
+## Color: support conversion from `String`
 
 Have you ever needed this conversion?
 
@@ -267,7 +267,7 @@ Color::from_str("#FF0000")   // Color::Rgb(255, 0, 0)
 
 ---
 
-### `Spans` -> `Line`
+## `Spans` -> `Line`
 
 `Line` is a significantly better name over `Spans` as the plural causes confusion and the type
 really is a representation of a line of text made up of spans.
@@ -280,7 +280,7 @@ for more discussion.
 
 ---
 
-### Other features
+## Other features
 
 - `List` now has a `len()` method for returning the number of items
 - `Sparkline` now has a `direction()` method for specifying the render direction (left to right /
@@ -290,7 +290,7 @@ for more discussion.
 
 ---
 
-### New apps
+## New apps
 
 Here is the list of applications that has been added:
 
@@ -305,7 +305,7 @@ applications built with `ratatui`!
 
 ---
 
-### Migration from `tui-rs`
+## Migration from `tui-rs`
 
 We put together a migration guide at the Wiki:
 [Migrating from TUI](https://github.com/ratatui-org/ratatui/wiki/Migrating-from-TUI)