render README.qmd/Rmd automatically

vincentarelbundock commented 10 months ago

When there is a README.qmd or a README.Rmd in the root directory, that file is rendered automatically to README.md at the very start of the process.

Then, README.md is copied over as we were doing before.

Since we now render all files with Quarto, the assets are stored in README.markdown_strict_files/ rather than README_assets/. I have kept both just in case we roll back to rmarkdown::render at some point.

netlify[bot] commented 10 months ago

Deploy Preview for upbeat-hamilton-47df84 ready!

Name	Link
Latest commit	b00e13e4c64d48641fb0c076e46042108d903644
Latest deploy log	https://app.netlify.com/sites/upbeat-hamilton-47df84/deploys/655f43c00330ce0008d36e3f
Deploy Preview	https://deploy-preview-124--upbeat-hamilton-47df84.netlify.app
Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

etiennebacher commented 10 months ago

I disagree on this one. The README.md already has to be present to appear on github, so we don't have to render it one more time. Suppose that the user forgot to render the README with the latest changes in the code but we do this rendering automatically, then the website and the README on github are not the same anymore, which can lead to confusion.

If the README is out-of-date on github, I think it should also be out-of-date on the website, and not fixed by us (which is similar to your argument in #123).

What do you think?

vincentarelbundock commented 10 months ago

Not all packages are published on Github, and altdoc should accommodate alternative workflows (see what I did there 😉)

Ad a user, I would expect render_docs() to execute and update every part of the website. It would be extremely weird to me as a user if render_docs() updated every part except the most important: the home page.

Perhaps you're thinking about packages like altdoc where the home page is rather static. But most of my packages have code on the home, and I want that to be executed and updated too.

Plus, I know I made the argument that website!=test, but your own counter argument applies here: if we don't run this automatically by default, the package can become out of sync with the site.

And if they don't want that, all they would have to do is store their qmd file elsewhere and keep only READMEmd in root.

vincentarelbundock commented 10 months ago

Finally, what's the downside? In altdoc repo it makes literally no difference because there is no file to render.

When there is a .qmd, it'll take 2 extra seconds to run it.

And i don't expect that any user will manually update .MD when they have a .QMD. when that's the case, the clearly want to generate the former and edit the latter.

etiennebacher commented 10 months ago

The thing I'm trying to say is that not rendering the README is different from not rendering the man pages:

no one reads the man folder on github (or any other service), people go to the website, which is why it's important to automatically render the man pages
some people only read the readme and some people go to the website. We don't want people to get different information depending on whether they look at the readme on github (or else) or if they look at the homepage

most of my packages have code on the home, and I want that to be executed and updated too.

I get that, but then you have to update ./README too, not just the docs/README. To me, here are the two behaviours:

currently: manually render README.Rmd, and then run render_docs(). Both the README and the homepage are up to date
this PR: render_docs() automatically renders the homepage, but not the original README. The homepage is up to date, not the README on github (or else)

Or maybe I misunderstood something?

vincentarelbundock commented 10 months ago

Yep yep, I agree with all this.

We don't want people to get different information depending on whether they look at the readme on github (or else) or if they look at the homepage

This is exactly the behavior I want to avoid!

I think that whenever the user modifies README.qmd, they must want that change to be reflected on both Github and the website. So I want render_docs() to automatically:

Render this in the root folder: /README.qmd -> /README.md so that the changes appear on Github.
Copy /README.md to docs/README.md so that the change is also reflected on the website.

That way, Github and the website are always kept in sync. In my view, there should be no altdoc based automatic workflow that would lead to differences between Github and the website, and the proposed workflow fixes that.

The only situation where this would not work is if the user makes changes to the raw code in README.qmd but does not want this to be updated on either Github or the website. In that case, I would recommend the user keep README.qmd in a different folder and only copies over README.md when they want to change the website.

etiennebacher commented 10 months ago

I think that whenever the user modifies README.qmd, they must want that change to be reflected on both Github and the website

Agreed with everything (I confused src_dir and tar_dir in the changes of this PR, which is why I thought this PR only modifies docs/README).

Glad to see we're on the same page then 👍

vincentarelbundock commented 10 months ago

Yeah, sometimes it takes me a while to explain a vision (because I just muddle along and figure it out as I go, lol)

etiennebacher / altdoc