Lint markdown docs #6480

joshka · 2024-04-12T21:04:18Z

docs: lint and reformat the main markdown files
style: automatically format ci.yaml

Motivation

When saving changes to markdown files in VSCode with a fairly standard setup (markdown lint extension installed),
often the extension will reformat areas of the docs unrelated to the the specific change. This PR makes everything
neat (100 character lines, consistent list characters, code languages on fenced code blocks etc.)

Solution

Reformatted the root level markdown docs
Added a markdown lint config file to set the line length (picked 100 chars as a reasonable compromise. 120 is generally too long for docs, while 80 seems overly constraining).
Added a markdown lint action to the ci.yml - currently this only points at the markdown docs in the root of the project, not those deeper in the project tree, but this could be ratcheted down to cover those once they're also similarly reformatted.

Includes a few small wording changes

joshka

Some quick explanations

joshka · 2024-04-12T21:06:45Z

CONTRIBUTING.md

-```
+```shell


In general, I've gone with shell over bash as the commands are relevant generally to any shell.

joshka · 2024-04-12T21:08:47Z

CONTRIBUTING.md

-```bash
-$ cd tokio
-$ cargo fuzz list
+```shell
+cd tokio
+cargo fuzz list
+```
+
+```text
 fuzz_linked_list
 ````


It's a good idea to generally split commands and the output into separate blocks instead of using shell prefixes, to make it clearer that the user shouldn't be pasting the output of the command.

joshka · 2024-04-12T21:10:52Z

CONTRIBUTING.md


 #### Commit message guidelines

 A good commit message should describe what changed and why.

 1. The first line should:
+   - contain a short description of the change (preferably 50 characters or less, and no more than


Using - for lists helps avoid the confusion between lists and italic / bold text

joshka · 2024-04-12T21:12:25Z

README.md

-More examples can be found [here][examples]. For a larger "real world" example, see the
+The Tokio github repository contains more [examples]. For a larger "real world" example, see the


Small content change here.

joshka · 2024-04-12T21:21:03Z

https://github.com/tokio-rs/tokio/actions/runs/8668104605/job/23772478137?pr=6481:

markdownlint-cli2 v0.13.0 (markdownlint v0.34.0)
Finding: *.{md,markdown}
Linting: 4 file(s)
Summary: 2 error(s)
Error: README.md:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "## Tokio"] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md041.md
Error: README.md:9:1 MD004/ul-style Unordered list style [Expected: dash; Actual: asterisk] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md004.md
Error: Failed with exit code: 1

Darksonn · 2024-04-12T22:07:55Z

README.md

-```text
+```toml
 tokio = { version = "~1.32", features = [...] }
 ```


This is rendered quite badly by github.

Agreed. What about one of the following instead?

tokio = { version = "~1.32", features = ["..."] }

tokio = { version = "~1.32", features = ... }

I don't have a strong preference, but the former seems more natural to me?

mox692

I left some notes regarding the small content changes I found, but all of these seem fine to me.

mox692 · 2024-04-13T10:59:35Z

README.md


-* **Fast**: Tokio's zero-cost abstractions give you bare-metal
-  performance.
+Tokio is:


content change: It is -> Tokio is

mox692 · 2024-04-13T11:01:33Z

README.md

@@ -58,7 +53,8 @@ Make sure you activated the full features of the tokio crate on Cargo.toml:
 [dependencies]
 tokio = { version = "1.37.0", features = ["full"] }
 ```
-Then, on your main.rs:
+
+Then, in your main.rs:


content change: on your main.rs -> in your main.rs

mox692 · 2024-04-13T11:04:31Z

README.md

- * `tokio-stream` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-stream/CHANGELOG.md)
- * `tokio-macros` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-macros/CHANGELOG.md)
- * `tokio-test` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-test/CHANGELOG.md)
+- [`tokio` changelog](https://github.com/tokio-rs/tokio/blob/master/tokio/CHANGELOG.md)


content change: view changelog -> changelog

mox692 · 2024-04-13T11:19:44Z

CONTRIBUTING.md


-`cargo install cargo-fuzz`
+```shell
+cargo install --locked cargo-fuzz


content change: cargo install cargo-fuzz -> cargo install --locked cargo-fuzz

mox692 · 2024-04-13T11:28:23Z

tokio/README.md


-* **Fast**: Tokio's zero-cost abstractions give you bare-metal
-  performance.
+Tokio is:


content change: It is -> Tokio is

mox692 · 2024-04-13T11:28:44Z

tokio/README.md

@@ -58,7 +53,8 @@ Make sure you activated the full features of the tokio crate on Cargo.toml:
 [dependencies]
 tokio = { version = "1.37.0", features = ["full"] }
 ```
-Then, on your main.rs:
+
+Then, in your main.rs:


content change: on your main.rs -> in your main.rs

Darksonn · 2024-05-01T14:27:51Z

I don't actually want to do this. We require code to pass rustfmt because otherwise we get too many PRs with badly formatted code. We don't have this problem with markdown, and I prefer the freedom that we currently have.

Either way, thank you for taking the time to submit a PR.

joshka added 2 commits April 12, 2024 13:57

docs: lint and reformat the main markdown files

e168842

Includes a few small wording changes

style: automatically format ci.yaml

e55f946

joshka commented Apr 12, 2024

View reviewed changes

docs: ensure tokio readme is identical to root readme

4070566

joshka mentioned this pull request Apr 12, 2024

Demonstrate markdown lint errors #6481

Draft

Darksonn reviewed Apr 12, 2024

View reviewed changes

mox692 reviewed Apr 13, 2024

View reviewed changes

mox692 added T-docs Topic: documentation A-readme Area: Documentation that isn't part of any crate such as README.md or CONTRIBUTING.md labels Apr 16, 2024

Darksonn closed this May 1, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Lint markdown docs #6480

Lint markdown docs #6480

joshka commented Apr 12, 2024

joshka left a comment

joshka Apr 12, 2024

joshka Apr 12, 2024

joshka Apr 12, 2024

joshka Apr 12, 2024

joshka commented Apr 12, 2024

Darksonn Apr 12, 2024

joshka Apr 13, 2024

mox692 Apr 13, 2024

mox692 left a comment

mox692 Apr 13, 2024

mox692 Apr 13, 2024

mox692 Apr 13, 2024

mox692 Apr 13, 2024

mox692 Apr 13, 2024

mox692 Apr 13, 2024

Darksonn commented May 1, 2024 •

edited

		More examples can be found [here][examples]. For a larger "real world" example, see the
		The Tokio github repository contains more [examples]. For a larger "real world" example, see the

		```
		```shell

Lint markdown docs #6480

Lint markdown docs #6480

Conversation

joshka commented Apr 12, 2024

Motivation

Solution

joshka left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joshka commented Apr 12, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mox692 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Darksonn commented May 1, 2024 • edited

Darksonn commented May 1, 2024 •

edited