Skip to content

Commit

Permalink
docs(style): add style guide to contributing
Browse files Browse the repository at this point in the history
  • Loading branch information
gforsyth committed Jan 25, 2024
1 parent 7ad32b1 commit 385f295
Showing 1 changed file with 56 additions and 0 deletions.
56 changes: 56 additions & 0 deletions docs/contribute/03_style.qmd
Original file line number Diff line number Diff line change
Expand Up @@ -35,3 +35,59 @@ If you use `nix-shell`, all of these are already setup for you and ready to use,
## Docstrings
We use [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) as our
standard format for docstrings.

## Documentation, blog, and other prose style

Always capitalize Ibis in prose.

### General points on style and word usage

Avoid the passive voice. Either Ibis does something or the user does
something or a particular backend does something.

Try to avoid using words like "simply", "simple", "obviously", "just", when
describing things that Ibis makes easier. Either the simplicity is
self-evident, or it isn't and you are inadvertently insulting the reader.

LLMs do not write well, they write _correctly_. These are not the same thing.


### Text formatting

Wrap long prose strings between 80-90 characters per line. It is very helpful
to reviewers when looking at diffs of prose.

- 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).

Do not commit Jupyter notebooks. You are more than welcome to author docs in
Jupyter but the `ipynb` file should be converted to `qmd`. (We use notebooks
for tutorials and interactive work, but for prose review, JSON is suboptimal).

Use `# Sentence case for section headers`, not `# Title Case for Headers`

### Quarto

Any computations that can't or shouldn't be done again should use `freeze: auto` in the YAML front matter.

::: {.callout-note}
**NEVER** use `freeze: true` as this results in silently stale pages.
:::

Format code blocks with `black` or `ruff` where possible.

Prefer `language` over `{.language}` in code blocks:

Prefer this:

```python
code here
```

Over this:

```{.python}
code here
```

0 comments on commit 385f295

Please sign in to comment.