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

Adding quarto extensions? #253

Open
coatless opened this issue Jan 19, 2024 · 12 comments
Open

Adding quarto extensions? #253

coatless opened this issue Jan 19, 2024 · 12 comments

Comments

@coatless
Copy link

👋 Hi

I'm interested in having altdocs generate a Quarto website that uses a few Quarto extensions.

After reading through the documentation on customization, I'm under the impression that any resource in altdoc will be copied entirely to _quarto before the website is rendered. So, if we place altdocs/_extensions, then any extension will be copied into _quarto for the render phase.

What I'm unsure about is whether I can write a script that modifies an intermediary generated when going from Rd to Qmd or md. Is this possible?

@etiennebacher
Copy link
Owner

What I'm unsure about is whether I can write a script that modifies an intermediary generated when going from Rd to Qmd or md. Is this possible?

Hi, I don't think it's possible for now but @vincentarelbundock is the one who added support for the Quarto website (and uses it more than me) so he might have more info. Just out of curiosity, why do you want to modify the intermediary qmd files?

@coatless
Copy link
Author

@etiennebacher thanks for the quick reply!

I'm interested in being able to stylize and modify different parts of the Quarto document before the final rendering. To add the styling, I need to register certain markup values that can be interpreted by a Quarto extension. I'm specifically interested in being able to have a "tabbed" section between rendered output and interactive output under the Example section.

P.S. Great to know that it was @vincentarelbundock who added it and is even using it for the famed modelsummary website package! 😄

@vincentarelbundock
Copy link
Collaborator

vincentarelbundock commented Jan 19, 2024

Hi @coatless

What you could try is to circumvent the altdoc automatic man creation altogether:

  • Loop over the files in man/
  • Call altdoc:::.rd2qmd() to convert them
  • Add your tabs
  • Add the output to the sidebar in YAML

This is obviously more "manual", but the hard part is to convert Rd to qmd anyway, and that part is automated. The rest is relatively trivial.

@coatless
Copy link
Author

@vincentarelbundock thanks for the quick feedback. I'll try to work on something this weekend or early next week.

If I can achieve what I set out to, would there be any desire to incorporate it as a feature into the package?

@vincentarelbundock
Copy link
Collaborator

Yeah, I think that might be useful. Not sure what a clean and general user interface would be. (With new features, I always try to think "could solving my one specific problem help me do other things?")

Once you know what is involved, feel free to post again and make a proposal. Ultimately it'll be @etiennebacher 's call, of course.

(Warning: I can review a PR, but I don't think either me or Etienne will have much---if any---time to write actual code.)

@coatless
Copy link
Author

coatless commented Jan 19, 2024

@vincentarelbundock awesome!

I should clarify: I'm not looking for any coding support; more of a home for the feature once I get it working. 😄

@etiennebacher
Copy link
Owner

etiennebacher commented Jan 19, 2024

Ultimately it'll be @etiennebacher 's call, of course.

The thing I want to avoid is adding code that could have side effects on other websites (I'm already spending way too much time on the docs of polars). I never use the "quarto_website" format for now so I don't have anything against adding new features for this but the changes should be limited to the quarto-related functions in altdoc (e.g .finalize_quarto_website()).

I should clarify: I'm not looking for any coding support; more of a home for the feature once I get it working.

Then hosting it in the altdoc folder in your package should be sufficient since it's never modified by altdoc::render_docs().

I'm curious to see what this will look like, feel free to add a link here when you have something working

@kylebutts
Copy link
Contributor

@coatless you can use a Quarto pre-render/post-render command for this, storing your script in altdoc/.

altdoc will set up _quarto/ with all the files and then call quarto::quarto_render() on the folder. If you have a pre-render script in your quarto_website.yml, this will be triggered when rendering, so you can modify the .qmd files programatically.

@coatless
Copy link
Author

An update of sorts a bit later than next weekend ;)

First, thanks @kylebutts for mentioning the pre-render portion. That did the trick! I wrote a quick R script that switches away from the historical R Markdown code chunks into Quarto's hashpipe style and, then, wraps the code cell with a Div that allowed for tabbifying content.

From there, I installed the extensions I needed to the altdocs/ directory. These were subsequently copied over to _quarto and still reside in docs/ once done.

To register the extensions and the pre-render, I made a few slight tweaks to the default quarto_website.yaml:

  1. I added a pre-render statement under project to run the above R Script.
  2. Set extension options globally for the project
    • I did assume that the first website URL corresponds to the GitHub website
  3. Attached the relevant extensions.

Lastly, I needed to modified the GitHub Action worker to include a second part... But, overall, I'm really happy with the outcome!

Source: https://github.com/coatless-r-n-d/quarto-webr-in-altdoc

Live Demo: https://rd.thecoatlessprofessor.com/quarto-webr-in-altdoc/man/in_webr.html

And a screenshot in case the live demo goes down while I'm still toying around 😉

Demo of altdoc including a quarto-webr code cell with static results generated

@etiennebacher
Copy link
Owner

etiennebacher commented Jun 11, 2024

That looks good, nice job! Is this something you would see integrated in the package? I'm thinking it might be easier to write a vignette on this so that we don't make the internals more complex.


Small aside: it looks like the native pipe doesn't work across lines, e.g:

mtcars |> arrange(drat)

works but not

mtcars |> 
  arrange(drat)

No clue if this is due to webr, quarto-webr or something else, I have no experience with those

@coatless
Copy link
Author

@etiennebacher wrote a brief vignette on the repo itself. I'd like to tweak at least the line I highlighted since it shouldn't be setting things with rmarkdown style options.


re: are you on windows? we've had odd eol issues. or were you trying cntrl + enter instead of shift + enter?

it's alive!

(cntrl + enter sends only the first line; whereas shift+ enter sends the code cell.) We can save this story for another day.

@etiennebacher
Copy link
Owner

were you trying cntrl + enter instead of shift + enter?

Ah I see, doing shift + enter works indeed, thanks!

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

No branches or pull requests

4 participants