Enable `freeze` functionality for `quarto_website` #262

kylebutts · 2024-03-20T18:19:39Z

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

- Add `output-dir` to avoid needing to copy files after running `quarto_render` - Avoid making `_quarto/docs/` folder when rendering. This is needed to use `_freeze/` folder correctly since that lives within `_quarto/`. - Add `execute:\n\tfreeze: auto` to `setup_docs` default `yml` file The transition to this would be any users to add ` output-dir: ../docs/` under `project` in their `quarto_website.yml`.

…utation

kylebutts · 2024-03-20T18:20:39Z

@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

etiennebacher

Hi @kylebutts, thanks for your contribution! I don't use quarto websites so @vincentarelbundock will have a better overview of whether this is good, but I just have one comment on the code.

R/settings_quarto_website.R

vincentarelbundock · 2024-03-21T00:29:07Z

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.

etiennebacher

Also, can you add a bullet point in the NEWS file?

kylebutts · 2024-03-21T10:43:39Z

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](https://quarto.org/docs/projects/code-execution.html#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. 

  ``` yml
  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 · 2024-03-21T11:03:53Z

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 · 2024-03-21T11:33:23Z

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 · 2024-03-21T11:34:46Z

@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 · 2024-03-21T12:19:55Z

@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. Adding quarto extensions? #253 (use quarto pre-render feature) and Quarto 1.4 arguments #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 · 2024-03-21T13:30:27Z

Very cool contribution, thanks!

etiennebacher

Thanks for the explanations, one last thing about the NEWS file

NEWS.md

etiennebacher · 2024-03-21T13:35:44Z

Ah too late 😅

vincentarelbundock · 2024-03-21T13:38:05Z

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

kylebutts added 5 commits March 20, 2024 13:02

If freeze == FALSE, delete the _freeze folder which forces recomp…

0301f16

…utation

Remove unnecessary dir_exists for dir_create

7b740ba

Use verbatim_logical to fix : yes/no issue with yaml

3c2e7d2

Simplify code for deleting files

31f26a8

etiennebacher reviewed Mar 20, 2024

View reviewed changes

R/settings_quarto_website.R Outdated Show resolved Hide resolved

etiennebacher reviewed Mar 21, 2024

View reviewed changes

fix styling issues

b5f576d

Add documentation for freeze option

3322cea

vincentarelbundock merged commit 8824669 into etiennebacher:main Mar 21, 2024
5 checks passed

etiennebacher reviewed Mar 21, 2024

View reviewed changes

NEWS.md Show resolved Hide resolved

etiennebacher mentioned this pull request Mar 25, 2024

Quarto website, is it necessary to delete full folder? #261

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enable `freeze` functionality for `quarto_website` #262

Enable `freeze` functionality for `quarto_website` #262

kylebutts commented Mar 20, 2024 •

edited

Loading

kylebutts commented Mar 20, 2024

etiennebacher left a comment

vincentarelbundock commented Mar 21, 2024

etiennebacher left a comment

kylebutts commented Mar 21, 2024 •

edited

Loading

etiennebacher commented Mar 21, 2024 •

edited

Loading

vincentarelbundock commented Mar 21, 2024

vincentarelbundock commented Mar 21, 2024

kylebutts commented Mar 21, 2024

vincentarelbundock commented Mar 21, 2024

etiennebacher left a comment

etiennebacher commented Mar 21, 2024

vincentarelbundock commented Mar 21, 2024

Enable freeze functionality for quarto_website #262

Enable freeze functionality for quarto_website #262

Conversation

kylebutts commented Mar 20, 2024 • edited Loading

kylebutts commented Mar 20, 2024

etiennebacher left a comment

Choose a reason for hiding this comment

vincentarelbundock commented Mar 21, 2024

etiennebacher left a comment

Choose a reason for hiding this comment

kylebutts commented Mar 21, 2024 • edited Loading

etiennebacher commented Mar 21, 2024 • edited Loading

vincentarelbundock commented Mar 21, 2024

vincentarelbundock commented Mar 21, 2024

kylebutts commented Mar 21, 2024

vincentarelbundock commented Mar 21, 2024

etiennebacher left a comment

Choose a reason for hiding this comment

etiennebacher commented Mar 21, 2024

vincentarelbundock commented Mar 21, 2024

Enable `freeze` functionality for `quarto_website` #262

Enable `freeze` functionality for `quarto_website` #262

kylebutts commented Mar 20, 2024 •

edited

Loading

kylebutts commented Mar 21, 2024 •

edited

Loading

etiennebacher commented Mar 21, 2024 •

edited

Loading