Enable `freeze` functionality for `quarto_website`

[kylebutts]

This PR enables the use of freeze functionality for _quarto websites. To enable freezing results of a file, add the following yml either to quarto_website.yml to enable site-wide or to the frontmatter of individual .qmd files:

execute:
  freeze: auto

The rendering logic is changed just a bit to render directly into docs/. For packages using altdoc, after this change, you need to add output-dir to your quarto_website.yml:

project:
  type: website
  output-dir: ../docs

Also fixed the annoying converting : yes to : true; there's a feature in yaml package

[kylebutts]

@vincentarelbundock Here's the PR. I figured out a much easier way when freeze = FALSE is to just delete the _freeze folder and it will have to re-render from scratch

[vincentarelbundock]

FWIW, I looked at the code and tried it on a couple repos. Looks like it works great!

When etienne's comment on <- arrows and my question above are answered, I expect to click "Merge".

Great contribution.

[kylebutts]

my question above are answered,

@vincentarelbundock I'm not seeing your questions

@etiennebacher I went to write a news item and wrote all of this; is this too long? I just wanted to document the feature; but maybe this goes somewhere else

## dev

### Breaking changes

* Simplified rendering for Quarto websites. Previously, the website was rendered into `_quarto/_site` and manually copied over to `docs/`. The new version removes this logic and instead uses the `output-dir` project option. To transition, change `quarto_website.yml` to:
  ``` yml
  project:
    output-dir: ../docs/

New features

• Quarto freeze is now fully supported using render_docs(freeze = TRUE). This allows Quarto to store results from .qmd files to prevent needing to rerender any document that hasn't had changes to code chunks.

  Note that changes to package functions that do not affect documentation will not trigger rerendering of files, so it is recommended to rebuild the docs completely with freeze = FALSE after working on the project. Doing so will delete the _quarto/_freeze cache, so be careful. With the new rendering changes above, you can render individual files using quarto::quarto_render(file) and it will be auto updated in the docs/ folder.

  Freezing a document needs to be set either at a project or per-file level. To do so, at the root level, add freeze: auto/true to either quarto_website.yml or the frontmatter of a file.

  execute:
  freeze: auto

Alternatively, can add the following to the help menu of render_docs:

#' @section Freeze
#' 
#' When working on a package, running `render_docs()` to preview changes can be a time-consuming road block. The argument `freeze = TRUE` tries to improve the experience by preventing rerendering of files that have not changed since the last time `render_docs()` was ran. Note that changes to package internals will not cause a rerender, so rerendering the entire docs can still be necessary. 
#' 
#' For non-Quarto formats, this is done by creating a `freeze.rds` file in `altdoc/` that is able to determine which documentation files have changed. 
#' 
#' For the Quarto format, we rely on the [Quarto freeze](https://quarto.org/docs/projects/code-execution.html#freeze) feature. Freezing a document needs to be set either at a project or per-file level. Freezing a document needs to be set either at a project or per-file level. To do so, add to either `quarto_website.yml` or the frontmatter of a file:
#'  ``` yml
#'  execute:
#'    freeze: auto
#'  ```
#' 

[etiennebacher]

Yes I think it is too long, more details should be added in the man page of render_docs(). Also, I'm not sure it's a breaking change because in the end the docs will still be stored in the folder docs, right? It sounds more like a bugfix to me.

With the new rendering changes, you can render individual files using quarto::quarto_render(file) and it will be auto updated in the docs/ folder.

Maybe I missed that earlier but I'm not sure this is desirable. I think ideally the docs folder should only be accessed/modified by altdoc (or by a user custom function). But once again I don't use quarto websites so Vincent will know better than me for this.

I can take a second look at the NEWS file just before merging, when Vincent will be happy about it.

Here's what I have in mind so far:

## development version

### Bug fixes

* `render_docs(freeze = TRUE)` now works correctly when output is `"quarto_website"`. Freezing a document needs to be set either at a project or per-file level. To do so, at the root level, add `freeze: auto/true` to either `quarto_website.yml` or the frontmatter of a file. 

  ``` yml
  execute:
    freeze: auto

(thanks Kyle Butts, #262)

--- 

(Edit: didn't see your suggestion for adding the section in the man page, I'm ok with that)

[vincentarelbundock]

With the new rendering changes, you can render individual files using quarto::quarto_render(file) and it will be auto updated in the docs/ folder.

Maybe I missed that earlier but I'm not sure this is desirable. I think ideally the docs folder should only be accessed/modified by altdoc (or by a user custom function). But once again I don't use quarto websites so Vincent will know better than me for this.

I think that's fine. IIUC, we're just enabling more options for users to work outside altdoc if they want to with custom functions, but that doesn't actually change anything to the altdoc workflow itself.

[vincentarelbundock]

@vincentarelbundock I'm not seeing your questions

You removed a check for if (!dir.exists(tar_dir)) { on line 42. I was just asking if that check was really extraneous, or if we should bring it back. Not a big deal, just curious.

[kylebutts]

@vincentarelbundock I'm not seeing your questions

You removed a check for if (!dir.exists(tar_dir)) { on line 42. I was just asking if that check was really extraneous, or if we should bring it back. Not a big deal, just curious.

fs::dir_create does not produce an error if the file already exists, so no need to check.

With the new rendering changes, you can render individual files using quarto::quarto_render(file) and it will be auto updated in the docs/ folder.

Maybe I missed that earlier but I'm not sure this is desirable. I think ideally the docs folder should only be accessed/modified by altdoc (or by a user custom function). But once again I don't use quarto websites so Vincent will know better than me for this.

Yes! Basically, the PR's render flow is (1) altdoc::render_docs sets up the _quarto/ folder with all the .qmd/.md files and copying over altdoc/, (2) Quarto renders this into a static website in docs/, and (3) altdoc copies over files from altdoc/ to docs/. This is not much different than the current system (just a bit more streamlined).

• Understanding the flow this way helps with, e.g. #253 (use quarto pre-render feature) and #260 (set default-image-extension: '' in format: html: in quarto_website.yml.

• My point re: rerendering of individaul files is that it's a nice dev experience. Say you wanted to quickly change something in a vignette and preview it in the docs. Then running quarto render on a single file will only run the single .qmd file and update the single .html file in docs/ and instantly it will show up with preview_docs(). To be clear, this is not a solution for rendering the complete docs correctly.

• Since we just call quarto render under the hood, this opens up the ability to have hugo-based docs and Docusaurus docs kind of for free (probably just a custom setup_docs()). Not recommending this be done, just pointing out another advantage

[vincentarelbundock]

Very cool contribution, thanks!

[etiennebacher]

Ah too late 😅

[vincentarelbundock]

Never too late with Git. But that seems like minor gray area stuff.