docs: refactor and move to quarto

qs

qs

qs

qs

qs

qs

qs

qs

qs

docs2/.gitignore

@@ -0,0 +1,14 @@
+.quarto
+_site
+
+*.ddb*
+
+index.ipynb
+
+site_libs
+
+*.csv
+*.parquet
+*.delta
+
+/.quarto/

docs2/README.md

@@ -0,0 +1,12 @@
+# Ibis documentation with Quarto
+
+TODO: update this README closer to merging.
+
+## Setup
+
+Checkout this PR/branch.
+
+0. Create a Python environment with everything installed
+1. Install Quarto
+2. Install justfile
+3. `just preview`

docs2/_callouts/experimental_backend.qmd

@@ -0,0 +1,3 @@
+::: {.callout-warning}
+The Polars backend is experimental and is subject to backwards incompatible changes.
+:::

docs2/_callouts/pypi_warning.qmd

@@ -0,0 +1,3 @@
+::: {.callout-warning} 
+Note that the `ibis-framework` package is _not_ the same as the `ibis` package in PyPI. These two libraries cannot coexist in the same Python environment, as they are both imported with the `ibis` module name.
+:::

docs2/_code/input_output_penguins.qmd

@@ -0,0 +1,187 @@
+## Data platforms
+
+You can connect Ibis to [any supported backend](#backends-supported) to read and write data in backend-native tables.
+
+```{python}
+# | code-fold: true
+
+con = ibis.duckdb.connect("penguins.ddb")
+t = con.create_table("penguins", t.to_pyarrow(), overwrite=True)
+```
+
+```{python}
+con = ibis.duckdb.connect("penguins.ddb")  # <1>
+t = con.table("penguins")  # <2>
+t.head(3)  # <3>
+```
+
+1. Connect to a backend.
+2. Load a table.
+3. Display the table.
+
+```{python}
+grouped = (  # <1>
+    t.group_by(["species", "island"])  # <1>
+    .aggregate(count=ibis._.count())  # <1>
+    .order_by(ibis.desc("count"))  # <1>
+)  # <1>
+con.create_table("penguins_grouped", grouped.to_pyarrow(), overwrite=True)  # <2>
+```
+
+1. Create a lazily evaluated Ibis expression.
+2. Write to a table.
+
+## File formats
+
+Depending on the backend, you can read and write data in several file formats.
+
+::: {.panel-tabset}
+
+## CSV
+
+```{.bash}
+pip install 'ibis-framework[duckdb]'
+```
+
+```{python}
+t.to_csv("penguins.csv")  # <1>
+ibis.read_csv("penguins.csv").head(3)  # <2>
+```
+1. Write the table to a CSV file. Dependent on backend.
+2. Read the CSV file into a table. Dependent on backend.
+
+## Delta Lake
+
+```{.bash}
+pip install 'ibis-framework[duckdb,deltalake]'
+```
+
+```{python}
+t.to_delta("penguins.delta", mode="overwrite")  # <1>
+ibis.read_delta("penguins.delta").head(3)  # <2>
+```
+
+1. Write the table to a Delta Lake table. Dependent on backend.
+2. Read the Delta Lake table into a table. Dependent on backend.
+
+## Parquet
+
+```{.bash}
+pip install 'ibis-framework[duckdb]'
+```
+
+```{python}
+t.to_parquet("penguins.parquet")  # <1>
+ibis.read_parquet("penguins.parquet").head(3)  # <2>
+```
+
+1. Write the table to a Parquet file. Dependent on backend.
+2. Read the Parquet file into a table. Dependent on backend.
+
+:::
+
+## With other Python libraries
+
+Ibis uses [Apache Arrow](https://arrow.apache.org/) for efficient data transfer to and from other libraries. Ibis tables implement the `__dataframe__` and `__array__` protocols, so you can pass them to any library that supports.
+
+::: {.panel-tabset}
+
+## pandas
+
+You can convert Ibis tables to pandas dataframes.
+
+```bash
+pip install pandas
+```
+
+```{python}
+df = t.to_pandas()  # <1>
+df.head(3)
+```
+
+1. Returns a pandas dataframe.
+
+Or you can convert pandas dataframes to Ibis tables.
+
+```{python}
+t = ibis.memtable(df)  # <1>
+t.head(3)
+```
+
+1. Returns an Ibis table.
+
+## Polars
+
+You can convert Ibis tables to Polars dataframes.
+
+```bash
+pip install polars
+```
+
+```{python}
+import polars as pl
+
+df = pl.from_arrow(t.to_pyarrow())
+df.head(3)
+```
+
+Or Polars dataframes to Ibis tables.
+
+```{python}
+t = ibis.memtable(df)
+t.head(3)
+```
+
+## PyArrow
+
+You can convert Ibis tables to PyArrow tables.
+
+```bash
+pip install pyarrow
+```
+
+```{python}
+t.to_pyarrow()
+```
+
+Or PyArrow batches:
+
+```{python}
+t.to_pyarrow_batches()
+```
+
+And you can convert PyArrow tables to Ibis tables.
+
+```{python}
+ibis.memtable(t.to_pyarrow()).head(3)
+```
+
+## PyTorch
+
+You can convert Ibis tables to torch tensors.
+
+```bash
+pip install torch
+```
+
+```{python}
+t.select(s.numeric()).limit(3).to_torch()
+```
+
+## `__dataframe__`
+
+You can directly call the `__dataframe__` protocol on Ibis tables, though this is typically handled by the library you're using.
+
+```{python}
+t.__dataframe__()
+```
+
+## `__array__`
+
+You can directly call the `__array__` protocol on Ibis tables, though this is typically handled by the library you're using.
+
+```{python}
+t.__array__()
+```
+
+:::

docs2/_code/setup_penguins.qmd

@@ -0,0 +1,14 @@
+```{python}
+import ibis  # <1>
+import ibis.selectors as s  # <1>
+
+ibis.options.interactive = True  # <2>
+
+t = ibis.examples.penguins.fetch()  # <3>
+t.head(3)  # <4>
+```
+
+1. Ensure you install Ibis first.
+2. Use interactive mode for exploratory data analysis (EDA) or demos.
+3. Load a dataset from the built-in examples.
+4. Display the table.

docs2/_quarto.yml

@@ -0,0 +1,128 @@
+project:
+  type: website
+
+execute: 
+  warning: false
+  error: false
+
+website:
+  title: "Ibis"
+  site-url: https://ibis-project.org
+  description: "the dataframe library"
+  favicon: logo.svg
+
+  # search
+  search:
+    location: navbar
+    type: textbox
+
+  # options
+  reader-mode: false
+  twitter-card: true
+  back-to-top-navigation: true
+  repo-url: https://github.com/ibis-project/ibis
+  repo-actions: [edit, issue]
+  issue-url: https://github.com/ibis-project/ibis/issues/new/choose
+
+  # footer
+  page-footer:
+    border: false
+    left: ""
+    right:
+      - icon: github
+        href: https://github.com/ibis-project
+      - icon: slack
+        href: https://gitter.im/ibis-dev/Lobby
+      - icon: rss
+        href: https://ibis-project.org/posts.xml
+
+  # nav
+  navbar:
+    logo: logo.svg
+    tools:
+      - icon: github
+        menu:
+          - text: Source code
+            url:  https://github.com/ibis-project/ibis
+          - text: Report a bug
+            url: https://github.com/ibis-project/ibis/issues/new?assignees=&labels=bug&projects=&template=bug-report.yml&title=bug
+          - text: Submit a feature request
+            url: https://github.com/ibis-project/ibis/issues/new?assignees=&labels=feature&projects=&template=feature-request.yml&title=feat
+          - text: Ask the community for help
+            url: https://github.com/ibis-project/ibis/discussions/new?category=q-a
+    left:
+      - sidebar:getting-started
+      - sidebar:concepts
+      - sidebar:backends
+      - sidebar:how-to
+      - sidebar:reference
+    right:
+      - posts.qmd
+      - community.qmd
+
+  sidebar:
+    - id: ""
+    - id: getting-started
+      title: "Getting started"
+      style: "docked"
+      collapse-level: 2
+      contents: 
+        - why.qmd
+        - install.qmd
+        - auto: tutorials/*.qmd
+    - id: concepts
+      title: "Concepts"
+      style: "docked"
+      collapse-level: 2
+      contents:
+        - what.qmd
+        - auto: concepts/*.qmd
+    - id: backends
+      title: "Backends"
+      style: "docked"
+      collapse-level: 2
+      contents: 
+        - support_matrix.qmd
+        - auto: backends/*.qmd
+    - id: how-to
+      title: "How-to"
+      style: "docked"
+      collapse-level: 2
+      contents:
+        - auto: "how-to/configure"
+        - auto: "how-to/input-output"
+        - auto: "how-to/analytics"
+        - auto: "how-to/visualization"
+        - auto: "how-to/old"
+    - id: community
+      title: "Community"
+      style: "docked"
+      collapse-level: 2
+      contents: 
+        - auto: community
+    - id: presentations
+      title: "Presentations"
+      style: "docked"
+      collapse-level: 2
+      contents: presentations
+    - id: reference
+      title: "Reference"
+      style: "docked"
+      collapse-level: 2
+      contents:
+        - auto: reference/*.qmd
+        - release_notes.qmd
+
+format:
+  html:
+    theme: 
+      light: flatly
+        #dark: darkly
+    css: styles.css
+    toc: true
+
+    # TODO: remove this after proper theme settled and ready to merge
+    # if using the vapor theme, adjust the text color optionally
+    #fontcolor: fuchsia
+    #linkcolor: fuchsia
+