docs: small README improvements

[maelle]

Fix #34

Other tweaks

• put installation instructions at the beginning.
• extract nearly all comments (apart from the CAVEAT that is inside a pipeline) from code chunks to make them more readable.
• clarify the titles of example sections.
• add link and short explanation of DuckDB.

[codecov-commenter]

Welcome to Codecov 🎉

Once merged to your default branch, Codecov will compare your coverage reports and display the results in this comment.

Thanks for integrating Codecov - We've got you covered ☂️

[krlmlr]

Thanks, looks good. I wonder if installation instructions should be at the beginning or at the end. The pak readme has them at the end, but would we need a ToC to support this? No strong preference.

I moved the library() calls up on purpose, otherwise the inline functions in "There are two ways to use duckplyr." are not linked. Maybe this should be handled differently in downlit? For now, I don't mind starting with library() calls before actually doing anything.

[maelle]

Thanks, looks good. I wonder if installation instructions should be at the beginning or at the end. The pak readme has them at the end, but would we need a ToC to support this? No strong preference.

The README has a ToC by default on GitHub anyway, however I am more used to seeing installation instructions at the beginning. 🤔

I moved the library() calls up on purpose, otherwise the inline functions in "There are two ways to use duckplyr." are not linked. Maybe this should be handled differently in downlit? For now, I don't mind starting with library() calls before actually doing anything.

I wanted the two examples to be self-contained as it means only one copy-paste to try them out. 😁 Maybe you can add a chunk with echo=FALSE that loads the library?

[krlmlr]

The examples are no longer self-contained because plain text separates them, you'll copy individual pieces anyway. I wonder if we can host the full examples in standalone build-ignored R scripts (with #+ comments that roxygen understands) and include them in the README?

I don't see the ToC in my GitHub.

[maelle]

I can't make any edit now, but regarding the TOC, if you click on the "three lines" icon near "README.md" you'll get a TOC. https://github.blog/changelog/2021-04-13-table-of-contents-support-in-markdown-files/ Now if even you don't know about this, many users won't know either.

[krlmlr]

Thanks!