[docs] Improve getting started guide

Made some improvements to the markdown text markup, as well as updated some text to reflect the current state of the project.

ESPHome now supports LibreTiny natively
Added extra PIO docs references
Reworded some sections slightly, to accomodate proper grammar
PIO deprecated the platformio platform install command, replaced this with the official recommendation/replacement
Replaced hard tabs with space characters. These break things less often, and are strongly preferred.

Tips for others:

A line break without creating a new paragraph can be accomplished by ending your line with two whitespace characters. You can see this being used in some of the unordered lists.
Use 4 space characters instead of tabs. Tabs have a tendency to display or behave inconsistently. This difference is already very visible between the GitHub web editor and Visual Studio Code.
Use the Prettier or Markdown All-In-One plugins for VS Code when writing Markdown. It helps you stay in line with the markdown writing guidelines.

Remarks:

The file lacks a trailing space character, which is required by the Markdown spec. This space character seems to get removed whenever something is committed through the GitHub web editor. I can't add it without spinning up a clone of the repo, which is beyond what I have time for at this very moment.

Hi Thanks for the PR. A couple of notes:

Whitespace characters at the end of line are impossible to see (I wouldn't guess they're here if not for your hint about lists :smile:), some editors actually strip them automatically when saving a file (my VSCode does). A good replacement is \, which works in MkDocs with the pymdownx.escapeall plugin. So I've replaced the whitespace with a backslash (except the "Run community projects" part, which looks better as a separate paragraph IMHO).
I'm not sure why would a trailing space character be necessary, there is a trailing newline character which is generally conceived a good practice, but to be fair any markdown renderer won't care about that anyway.
I've replaced the Git link in pio pkg install with just libretiny, since it's available in PIO registry.

Lastly, I like to keep using the tab character for indentation. I know this entire topic is an open discussion in the Internet (or is it a war?), but any sane editor/IDE will allow to customize the tab width to your liking (which can't be done if using whitespace). That is my main reason for using tabs instead of spaces (whereas in e.g. ESPHome I'm forced to use 2 spaces which makes the code totally unreadable). Also, navigation using arrows is much easier (pressing 4x less keys), using Delete is easier, selecting code to copy/paste is easier (I'm more of a keyboard person).

Other than this - approved, I'll merge unless you have something else to add/change.

You can use shift key and control key as modifiers for the backspace key. They remove entire lines or entire words/whitespace separated sections.

If I said to leave a space character at the end of the file, I did mean a newline. The git diff on GitHub didn't show a newline, so I was under the impression that it had removed it in the process of submitting.

The same reasons you specify for not liking space characters instead of tab characters is the same set of reasons programmers often prefer space characters. They are very deterministic and have a predictable effect.

Vs code has a setting bottom right where you can define what you'd like to use as a tab. You can set it to a tab, or anywhere from one to four space characters. Vs code will treat tabs created with spaces as tabs and they will delete / indent as expected.

Cheers. :)

On Mon, 19 Feb 2024, 9:56 pm Kuba Szczodrzyński, @.***> wrote:

Hi Thanks for the PR. A couple of notes:

Whitespace characters at the end of line are impossible to see (I wouldn't guess they're here if not for your hint about lists 😄), some editors actually strip them automatically when saving a file (my VSCode does). A good replacement is \, which works in MkDocs with the pymdownx.escapeall plugin https://facelessuser.github.io/pymdown-extensions/extensions/escapeall/. So I've replaced the whitespace with a backslash (except the "Run community projects" part, which looks better as a separate paragraph IMHO).

I'm not sure why would a trailing space character be necessary, there is a trailing newline character which is generally conceived a good practice, but to be fair any markdown renderer won't care about that anyway.

I've replaced the Git link in pio pkg install with just libretiny, since it's available in PIO registry.

Lastly, I like to keep using the tab character for indentation. I know this entire topic is an open discussion in the Internet (or is it a war?), but any sane editor/IDE will allow to customize the tab width to your liking (which can't be done if using whitespace). That is my main reason for using tabs instead of spaces (whereas in e.g. ESPHome I'm forced to use 2 spaces which makes the code totally unreadable). Also, navigation using arrows is much easier (pressing 4x less keys), using Delete is easier, selecting code to copy/paste is easier (I'm more of a keyboard person).

Other than this - approved, I'll merge unless you have something else to add/change.

— Reply to this email directly, view it on GitHub https://github.com/libretiny-eu/libretiny/pull/252#issuecomment-1953149334, or unsubscribe https://github.com/notifications/unsubscribe-auth/AD32W6DAXVFUO6QDTDNGEGTYUO373AVCNFSM6AAAAABDP7ABDSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNJTGE2DSMZTGQ . You are receiving this because you authored the thread.Message ID: @.***>

They are very deterministic and have a predictable effect.

Well, the effect will be the same even if we use 5 spaces to indent lines :smile: MkDocs won't care anyway, HTML doesn't render anything of that. So I guess this just affects writing docs, not viewing them.

Vs code has a setting bottom right where you can define what you'd like to use as a tab.

It does, but if a particular project is indented with 2 spaces (ESPHome in this case), I am forced to see it like that, and I can't change the width to 4 [characters] to make the code look less squished. Using tabs I can choose whatever I want on my end, each developer can do what they prefer.

If I said to leave a space character at the end of the file, I did mean a newline. The git diff on GitHub didn't show a newline, so I was under the impression that it had removed it in the process of submitting.

It does indeed keep the newline. In fact, if there's no newline it will show :no_entry: icon at the end.

Pydown definitely does care about indentation! It's an important hierarchy indicator.

On Mon, 19 Feb 2024, 10:17 pm Kuba Szczodrzyński, @.***> wrote:

They are very deterministic and have a predictable effect.

Well, the effect will be the same even if we use 5 spaces to indent lines 😄 MkDocs won't care anyway, HTML doesn't render anything of that. So I guess this just affects writing docs, not viewing them.

Vs code has a setting bottom right where you can define what you'd like to use as a tab.

It does, but if a particular project is indented with 2 spaces (ESPHome in this case), I am forced to see it like that, and I can't change the width to 4 [characters] to make the code look less squished. Using tabs I can choose whatever I want on my end, each developer can do what they prefer.

If I said to leave a space character at the end of the file, I did mean a newline. The git diff on GitHub didn't show a newline, so I was under the impression that it had removed it in the process of submitting.

It does indeed keep the newline. In fact, if there's no newline it will show ⛔ icon at the end.

— Reply to this email directly, view it on GitHub https://github.com/libretiny-eu/libretiny/pull/252#issuecomment-1953167972, or unsubscribe https://github.com/notifications/unsubscribe-auth/AD32W6FALQXRK5AUERS2EDDYUO6N5AVCNFSM6AAAAABDP7ABDSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNJTGE3DOOJXGI . You are receiving this because you authored the thread.Message ID: @.***>

libretiny-eu / libretiny

[docs] Improve getting started guide #252

Tips for others:

Remarks: