Closed kylebutts closed 5 months ago
@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
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.
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/
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
#' ```
#'
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 thedocs/
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)
With the new rendering changes, you can render individual files using
quarto::quarto_render(file)
and it will be auto updated in thedocs/
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 byaltdoc
(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 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.
@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 thedocs/
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 byaltdoc
(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
Very cool contribution, thanks!
Ah too late 😅
Never too late with Git. But that seems like minor gray area stuff.
This PR enables the use of
freeze
functionality for_quarto
websites. To enable freezing results of a file, add the following yml either toquarto_website.yml
to enable site-wide or to the frontmatter of individual.qmd
files:The rendering logic is changed just a bit to render directly into
docs/
. For packages usingaltdoc
, after this change, you need to addoutput-dir
to yourquarto_website.yml
:Also fixed the annoying converting
: yes
to: true
; there's a feature inyaml
package