Bringing the tree up to formatting parity with clang-format, shellcheck, shfmt, yaml linting, and MD lint (#432)
* Initial restyle
* Updating json and pretty
* Adding editorconfig
* Forcing us to use common pretty-ify versions
* Manually moving this up, fixing more pinning
* restyle devcontainer
* Pulling upstream
* Keeping travis off restyled
* Testing fix for codecov
diff --git a/docs/STYLE_GUIDE.md b/docs/STYLE_GUIDE.md
index f576502..7e439f5 100644
--- a/docs/STYLE_GUIDE.md
+++ b/docs/STYLE_GUIDE.md
@@ -2,31 +2,35 @@
CHIP documentation lives here:
-* **GitHub** — All guides and tutorials across the complete [Project-CHIP organization](https://github.com/project-chip).
+- **GitHub** — All guides and tutorials across the complete
+ [Project-CHIP organization](https://github.com/project-chip).
-See [CONTRIBUTING.md](../CONTRIBUTING.md) for general information on contributing to this project.
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for general information on
+contributing to this project.
## Location
-Place all documentation contributions in the appropriate location in the [`/docs`](./) directory. Most contributions should go into the `/docs/guides` subdirectory, which covers conceptual and usage content.
+Place all documentation contributions in the appropriate location in the
+[`/docs`](./) directory. Most contributions should go into the `/docs/guides`
+subdirectory, which covers conceptual and usage content.
Current documentation structure:
-Directory | Description
-----|----
-`/actions` | Custom GitHub actions
-`/docs/guides` | Conceptual or usage content that doesn't fit within a subdirectory, and high-level tutorials
-`/docs/guides/images` | All images included in guide content
-`/docs/guides/profiles` | Content describing or illustrating use of CHIP profiles
-`/docs/guides/test` | Content related to testing CHIP
-`/docs/guides/tools` | Content describing or illustrating use of CHIP tools
-`/docs/guides/primer` | CHIP Primer content
-`/docs/presentations` | PDF presentations on CHIP features
-`/docs/specs` | PDFs of CHIP specifications
-`/images` | Top-level CHIP images, such as logos
+| Directory | Description |
+| ----------------------- | -------------------------------------------------------------------------------------------- |
+| `/actions` | Custom GitHub actions |
+| `/docs/guides` | Conceptual or usage content that doesn't fit within a subdirectory, and high-level tutorials |
+| `/docs/guides/images` | All images included in guide content |
+| `/docs/guides/profiles` | Content describing or illustrating use of CHIP profiles |
+| `/docs/guides/test` | Content related to testing CHIP |
+| `/docs/guides/tools` | Content describing or illustrating use of CHIP tools |
+| `/docs/guides/primer` | CHIP Primer content |
+| `/docs/presentations` | PDF presentations on CHIP features |
+| `/docs/specs` | PDFs of CHIP specifications |
+| `/images` | Top-level CHIP images, such as logos |
-If you are unsure of the best location for your contribution, create an Issue and ask, or let us know in your Pull Request.
-
+If you are unsure of the best location for your contribution, create an Issue
+and ask, or let us know in your Pull Request.
## Style
@@ -42,19 +46,26 @@
## Markdown guidelines
-Use standard Markdown when authoring CHIP documentation. While HTML may be used for more complex content such as tables, use Markdown as much as possible.
+Use standard Markdown when authoring CHIP documentation. While HTML may be used
+for more complex content such as tables, use Markdown as much as possible.
> Note: Edit this file to see the Markdown behind the examples.
### Headers
-The document title should be an h1 header (#) and in title case (all words are capitalized). All section headers should be h2 (##) or lower and in sentence case (only the first word and proper nouns are capitalized).
+The document title should be an h1 header (#) and in title case (all words are
+capitalized). All section headers should be h2 (##) or lower and in sentence
+case (only the first word and proper nouns are capitalized).
-The best practice for document clarity is to not go lower than h3, but h4 is fine on occasion. Try to avoid using h4 often, or going lower than h4. If this happens, the document should be reorganized or broken up to ensure it stays at h3 with the occasional h4.
+The best practice for document clarity is to not go lower than h3, but h4 is
+fine on occasion. Try to avoid using h4 often, or going lower than h4. If this
+happens, the document should be reorganized or broken up to ensure it stays at
+h3 with the occasional h4.
### Command line examples
-Feel free to use either `$` or `%` to preface command line examples, but be consistent within the same doc or set of docs:
+Feel free to use either `$` or `%` to preface command line examples, but be
+consistent within the same doc or set of docs:
```
$ git clone https://github.com/project-chip/connectedhomeip.git
@@ -63,14 +74,16 @@
### Terminal prompts
-If you need use a full terminal prompt with username and hostname, use the format of `root@{hostname}{special-characters}#`.
+If you need use a full terminal prompt with username and hostname, use the
+format of `root@{hostname}{special-characters}#`.
-For example, when logged into a Docker container, you might have a prompt like this:
+For example, when logged into a Docker container, you might have a prompt like
+this:
+
```
root@c0f3912a74ff:/#
```
-
### Commands and output
All example commands and output should be in code blocks with backticks:
@@ -79,15 +92,17 @@
code in backticks
```
-...unless the code is within a step list. In a step list, indent the code blocks:
+...unless the code is within a step list. In a step list, indent the code
+blocks:
code indented
### Code blocks in step lists
-When writing procedures that feature code blocks, indent the content for the code blocks:
+When writing procedures that feature code blocks, indent the content for the
+code blocks:
-1. Step one:
+1. Step one:
$ git clone https://github.com/project-chip/connectedhomeip.git
$ cd connectedhomeip
@@ -96,8 +111,9 @@
$ ./configure
-For clarity in instructions, avoid putting additional step commands after a code sample
-within a step item. Instead rewrite the instruction so this is not necessary.
+For clarity in instructions, avoid putting additional step commands after a code
+sample within a step item. Instead rewrite the instruction so this is not
+necessary.
For example, avoid this:
@@ -111,19 +127,19 @@
1. Step three, do this now, and you will see that thing:
- $ ./configure
+ $ ./configure
### Inline code
-Use backticks for `inline code`. This includes file paths and file or binary names.
+Use backticks for `inline code`. This includes file paths and file or binary
+names.
### Code Comments
Use uppercase `CHIP` in comments, as it is an acronym.
-
Supported keywords:
-Keyword | Description
-----|----
-alarm | Alarm
+| Keyword | Description |
+| ------- | ----------- |
+| alarm | Alarm |
