docs(style): add style guide to contributing #8092
Conversation
|
idk what this is called but should have something about section headers -- "They should always be like this" instead of "Them Being Like This" "sentence case" vs "title case" according to my good friend chatgpt |
| **NEVER** use `freeze: true` as this results in silently stale pages. | ||
| ::: | ||
|
|
||
| Format code blocks with `black` or `ruff` where possible. |
There was a problem hiding this comment.
Since Ibis uses ruff now, should we just stick to ruff.
If we don't care about this, and we would accept black, it might be worth considering this quarto extension https://github.com/shafayetShafee/black-formatter
There was a problem hiding this comment.
the style differences are extremely minimal, but an auto-formatter for the quarto code blocks would be nice.
There was a problem hiding this comment.
The only thing that makes me hesitant is that the formatting happens at the rendering level, it doesn't modify the file. I'll look into it a bit more, that being said that's out of the scope of this PR.
docs/contribute/03_style.qmd
Outdated
|
|
||
| Format code blocks with `black` or `ruff` where possible. | ||
|
|
||
| Prefer `language` over `{.language}` in code blocks: |
There was a problem hiding this comment.
I'm not sure I follow this one, is this for non-executable cells?
There was a problem hiding this comment.
yep, adding a comment about that.
| - In vim you can use `gq` and then a movement to wrap. `gqG` to wrap an entire document. | ||
| - In neovim you can use `gw` and then a movement to wrap. `gwG` to wrap and entire document. | ||
| - In emacs you can use `fill-paragraph`. | ||
| - VSCode has a plugin called Rewrap (and probably several others). |
There was a problem hiding this comment.
the VIM commands also work if you're using it in VSCode as one should
There was a problem hiding this comment.
Do you mean if you're using the vim plugin / mode inside VSCode?
There was a problem hiding this comment.
yep! so I use gq and whatnot in VSCode
|
|
||
| Format code blocks with `black` or `ruff` where possible. | ||
|
|
||
| Prefer `language` over `{.language}` for non-executable code blocks: |
There was a problem hiding this comment.
why? I thought quarto convention was the opposite
There was a problem hiding this comment.
It is, but it seems like a bad convention. More typing overall and also more prone to accidentally making a block executable.
|
This can be squashed down when we merge it in, but I left the wrapping of previously existing lines in a separate commit if folks want to view those changes separately. |
docs/contribute/03_style.qmd
Outdated
|
|
||
| ### Text formatting | ||
|
|
||
| Wrap long prose strings between 80-90 characters per line. It is very helpful |
There was a problem hiding this comment.
Is it possible to just pick a number? :) Like 80 or 88?
There was a problem hiding this comment.
I can specify an upper bound, how about that?
|
The preference for sentence case is on line 92 |
Description of changes
Adding a first version of our unwritten style guide for prose and documentation.
Issues closed
Resolves #7094