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

Enable freeze functionality for quarto_website #262

Merged
merged 7 commits into from
Mar 21, 2024
Merged

Enable freeze functionality for quarto_website #262

merged 7 commits into from
Mar 21, 2024

Conversation

kylebutts
Copy link
Contributor

@kylebutts kylebutts commented Mar 20, 2024

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`.
@kylebutts
Copy link
Contributor Author

@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

Copy link
Owner

@etiennebacher etiennebacher left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Outdated Show resolved Hide resolved
@vincentarelbundock
Copy link
Collaborator

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.

Copy link
Owner

@etiennebacher etiennebacher left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@kylebutts
Copy link
Contributor Author

kylebutts commented Mar 21, 2024

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

etiennebacher commented Mar 21, 2024

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

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

@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
Copy link
Contributor Author

@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 vincentarelbundock merged commit 8824669 into etiennebacher:main Mar 21, 2024
5 checks passed
@vincentarelbundock
Copy link
Collaborator

Very cool contribution, thanks!

Copy link
Owner

@etiennebacher etiennebacher left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

NEWS.md Show resolved Hide resolved
@etiennebacher
Copy link
Owner

Ah too late 😅

@vincentarelbundock
Copy link
Collaborator

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants