Prototype converting ibis backends pages to quarto

[machow]

Currently, the ibis backends pages are generated from...

• a backend markdown page (e.g. backends/bigquery.md)
• yaml at the top of each backend page
• An {% include 'backends/badges.md' %} statement, which inserts some markdown.
  • Importantly badges.md uses some of the variables defined in the yaml topmatter for e.g. bigquery.md.

Let's figure out a nice translation of this workflow to quarto.

Possible solution

One option might be to include a set of parameters in a python code block? Then, you could include a badges.qmd that used these parameters to generate some markdown.

For example:

bigquery.qmd

```{python}
backend_name = "Google BigQuery"
backend_url = "https://cloud.google.com/bigquery"
exports = ["PyArrow", "Parquet", "CSV", "Pandas"]
imports = []

{{< include badges.qmd >}}

**badges.qmd**

#| output: asis

if imports:
    ...

if exports:
    ...

### Something else?

I wouldn't be surprised if there's some other simpler way!

[machow]

@hamelsmu, if you have some time, do you mind exploring this?

[hamelsmu]

What is the front matter doing exactly? I see the BigQuery page but what to sanity check -- Is all this stuff just for the badge? at the top of the page?

---
backend_name: Google BigQuery
backend_url: https://cloud.google.com/bigquery
exports: ["PyArrow", "Parquet", "CSV", "Pandas"]
---

{% include 'backends/badges.md' %}

I feel like I could be missing something. But seems like quite a complicated way to include a badge! My main question is why have it in the front matter at all? This seems kind of idiosyncratic to this particular library, why not forget the includes and make this a small python package like so:

#|output: asis
#|echo: false
from ibis_quarto import badge
badge(exports = ["PyArrow", "Parquet", "CSV", "Pandas"])

WDYT? It could also be a small python script that you import and add to your path.

[machow]

Thanks for weighing in--I tried out your suggestion of just using a function, and it definitely seems way nicer (https://github.com/machow/ibis-docs-demo/pull/5). I didn't notice on the first pass, but it looks like there's quite a bit more logic in template.md.

But apparently it's all jinja2, so writing a function to render the jinja template, and keep it as output: asis wasn't too crazy.

[hamelsmu]

@machow and I pair programmed a solution here