Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: small README improvements #57

Merged
merged 4 commits into from
Oct 15, 2023
Merged

docs: small README improvements #57

merged 4 commits into from
Oct 15, 2023

Conversation

maelle
Copy link
Collaborator

@maelle maelle commented Sep 18, 2023

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.

@maelle maelle requested a review from krlmlr September 18, 2023 07:24
@codecov-commenter
Copy link

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
Copy link
Member

krlmlr commented Sep 19, 2023

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
Copy link
Collaborator Author

maelle commented Sep 19, 2023

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
Copy link
Member

krlmlr commented Sep 19, 2023

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.

image

@maelle
Copy link
Collaborator Author

maelle commented Sep 19, 2023

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 krlmlr merged commit 3003aeb into tidyverse:main Oct 15, 2023
1 check passed
@krlmlr
Copy link
Member

krlmlr commented Oct 15, 2023

Thanks!

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Oct 15, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

create R-universe, add installation instructions from R-universe?
3 participants