add clarity formatter guide

[ryanwaits]

What does this PR do?

Add a guide going over the new Clarity formatter in vscode and clarinet.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
hiro-systems-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 19, 2025 3:46am

[max-crawford]

I made some copy edits to the guide. One overarching question i have is this section feels a bit out of place alongside the other Clarinet guides. The other guides teach devs how to do things, whereas this guide mostly explains formatting rules. I wonder if this should be broken apart in docs into 2 components:

1. A "guide" called "Format your Clarity code" or "Configure Clarity formatter" that teaches devs how to engage with the Clarity formatter feature, how to configure its settings, etc. (basically keeping this guide as is, but removing all of the formatting rules)

2. A reference for all of the individual formatting rules. Maybe that exists below "concepts" in the Clarinet section, in a new reference section for Clarinet, or maybe the formatting rules exist in the Clarity section of docs.

[ryanwaits]

A "guide" called "Format your Clarity code" or "Configure Clarity formatter" that teaches devs how to engage with the Clarity formatter feature, how to configure its settings, etc. (basically keeping this guide as is, but removing all of the formatting rules)

i see the points here, i had thought about it - but it ultimately doesn't feel like it warrants splitting into two. if the guide feels too long or doesn't flow well that's one thing, but breaking it into two for something as simple/straightforward as a formatter just seems like overkill to me.

A reference for all of the individual formatting rules. Maybe that exists below "concepts" in the Clarinet section, in a new reference section for Clarinet, or maybe the formatting rules exist in the Clarity section of docs.

yeah i thought on this a bit as well, what i landed on re: Clarity section was that the formatter is a tool that helps developers work with Clarity code, and the Clarity section focuses more on the language itself (syntax, functions, best practices for writing Clarity code) so it felt like this belonged with the Clarinet section vs Clarity section.

though i will say moving it outside of the Guides section on the sidebar and just as a standalone reference is the best solution, which is what i've done.

[tippenein]

Looks great 💯

[max-crawford]

looks good to me!

[hugocaillard]

@tippenein

Could you add a section explaining how to disable/enable Clarity LSP formatting in VSCode (maybe with a screenshot)

As well as how to enable/disable format on save for a given language in VSCode.

"[clarity]": {
    "editor.formatOnSave": true,
  },

I think it can be helpful for beginners