`quarto inspect` docs, specs, tests

[cscheid]

Let's document the output of quarto inspect and test so we don't accidentally change its behavior going forward.

(cc @aronatkins)

[cderv]

I understand you are interested by any existing usage.

I know quarto inspect is used in R ecosystem for tooling that needs to handle workflow, for example targets (appeared in discussion at https://github.com/quarto-dev/quarto-r/issues/14#issuecomment-1172325608) - they use quarto::quarto_inspect() to get rendered file information (https://github.com/ropensci/tarchetypes/blob/3aff790f6a899b40b3fd62151a6b243c06ef12a2/R/tar_quarto_files.R#L60-L91)

Related feature request for this usage:

• https://github.com/quarto-dev/quarto-cli/issues/8397

This usage is good to know if we touch quarto inspect

Other known usage are Posit Connect deployment related

• rsconnect-python python module https://github.com/rstudio/rsconnect-python/blob/18bfc5a5ac5b0ea03a2b9610dd04685e3919bd7f/rsconnect/actions.py#L460-L478
• rsconnect R 📦 : https://github.com/rstudio/rsconnect/blob/81b18c95c43d33cb395d6bef66b90d6aa5cc2075/R/deploySite.R#L102

[Lytol]

It would also be enormously useful to see parameters (default values, types, etc), similar to how papermill exposes them via papermill inspect (docs).

[cscheid]

@Lytol Thanks for recording that. As I mentioned on Slack, the main problem here is that execution parameterization is done differently depending on engines, and we don't have a unified API to handle both. Concretely, the jupyter engine handles parameterization through papermill, but the knitr engine handles parameterization directly via the params yaml configuration.

With that said, we are soon going to land a third-party, pure-Julia engine to Quarto, and I'm sure they'd like parameterization to be supported as well. So maybe this is something we can solve all at once.

[cderv]

we don't have a unified API to handle both.

@cscheid I think we should come up with something like that to make parameters a language agnostic features like others. I think we have several issues related to parameters. I am thinking we could open an EPIC-like issue to start regrouping all of them maybe. ok with you ?

[aronatkins]

The quarto.version and engines fields are used by rsconnect: https://github.com/rstudio/rsconnect/blob/81b18c95c43d33cb395d6bef66b90d6aa5cc2075/R/appMetadata-quarto.R#L15-L18

The quarto.version and engines fields are used by rsconnect-python. The config.project.render is also used, but that will probably switch to using files.input. The project.output-files is also used. https://github.com/rstudio/rsconnect/blob/81b18c95c43d33cb395d6bef66b90d6aa5cc2075/R/appMetadata-quarto.R#L15-L18 https://github.com/rstudio/rsconnect-python/blob/818d393c3b802136014839c927698ef5a7352779/rsconnect/bundle.py#L323-L334 https://github.com/rstudio/rsconnect-python/blob/818d393c3b802136014839c927698ef5a7352779/rsconnect/bundle.py#L1302-L1312

The version information is used by Connect when trying to discover a compatible server-configured version of Quarto.

The engines information is used by rsconnect/rsconnect-python to determine if it should capture Python/R project dependencies. It is also used by Connect to help determine if Python/R packages need to be installed and if a Jupyter kernel is needed.

The config.project and config.project.render fields were used by rsconnect-python to determine if content was a "multi-file" project, but the current approach can get that wrong.

The config.project.render field is also used by rsconnect-python to add some additional "ignore" locations, but we will likely switch to files.input.

The project.output-dir is used by rsconnect-python to add some "ignore" locations when assembling the bundle.

Additionally, the output directory is used by Connect, as it identifies where the rendering result lands. Content without an incoming output directory is given one by Connect, so the rendered result is separate from the working directory. We determine if we need to configure an output directory by using the inspect output to determine if we need to create/adjust the _quarto.yml.