Migrate documentation to Quarto (#712)

.github/workflows/publish-docs.yml

@@ -5,16 +5,18 @@ on:
     branches:
       - main
   pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
 
 jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
     steps:
-      - name: Set up Pandoc
-        uses: r-lib/actions/setup-pandoc@v2
-
       - name: Checkout source
         uses: actions/checkout@v2
         with:
@@ -25,37 +27,31 @@ jobs:
         with:
           python-version: "3.10"
 
-      - name: Install Bambi and all its dependencies
+      - name: Install quartodoc and griffe
         run: |
-          conda install -c conda-forge python-graphviz
-          conda install pip
-          pip install .
-          pip install .[dev]
-          pip install .[jax]
+          python -m pip install --upgrade pip
+          python -m pip install quartodoc==0.4.2
+          python -m pip install griffe==0.32.3
 
-      - name: Checkout gh-pages
-        uses: actions/checkout@v2
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2   
         with:
-          ref: gh-pages
-          path: docs/_build/html
-
-      - name: Test build docs
-        if: github.ref != 'refs/heads/main' && ! startsWith(github.ref, 'refs/tags')
-        run: BUILDDIR=_build/html/main make -C docs/ local
+          version: 1.2.280 # since this is my local version, we could change it
 
       - name: Build docs
-        if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags')
+        shell: bash
         run: |
-          sphinx-build docs docs/_build/html
-          touch docs/_build/html/.nojekyll
-
-      - name: Publish docs to gh-pages
-        # Only once from main or a tag
-        if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags')
-        # We pin to the SHA, not the tag, for security reasons.
-        # https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
-        uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501 # v3.7.3
+          python -m quartodoc build --config docs/_quarto.yml
+          quarto render docs
+          touch docs/_site/.nojekyll
+
+      - name: Publish to GitHub 
+        if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags') # Only from main or a tag
+        uses: quarto-dev/quarto-actions/publish@v2
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/_build/html
-          keep_files: true
+          target: gh-pages
+          render: false
+          path: docs/_site
+
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -17,4 +17,5 @@ tags
 .cache
 docs/_build
 .vscode/
-pytest.ini
+pytest.ini
+/.quarto/

docs/.gitignore

@@ -0,0 +1,4 @@
+/.quarto/
+_site
+api/*
+CHANGELOG.md

docs/_quarto.yml

@@ -0,0 +1,138 @@
+project:
+  type: website
+  output-dir: _site
+  pre-render: pre_render.py
+  #post-render: post_render.py
+  resources: 
+    - api/**
+
+website:
+  title: "Bambi"
+  description: "BAyesian Model Building Interface in Python"
+  repo-url: https://github.com/bambinos/bambi
+  page-navigation: true
+  favicon: "logos/favicon.png"
+  page-footer:
+    center: © Copyright 2023, The developers of Bambi.
+  navbar:
+    title: false
+    background: light
+    search: true
+    pinned: true
+    logo: "logos/RGB/Bambi_logo.png"
+    logo-alt: "bambi-home"
+    right:
+      - text: Reference
+        href: api/index.html
+      - text: Examples
+        href: notebooks/index.qmd
+      - text: FAQ
+        file: faq.qmd
+      - text: Changelog
+        file: CHANGELOG.md
+      - icon: github
+        href: https://github.com/bambinos/bambi
+
+  sidebar:
+    - id: reference
+      contents: _sidebar.yml
+    - id: examples
+      style: floating
+      collapse-level: 1
+      contents:
+        - notebooks/index.qmd
+        - section: Linear regression models
+          contents:
+            - notebooks/t-test.ipynb
+            - notebooks/ESCS_multiple_regression.ipynb
+            - notebooks/splines_cherry_blossoms.ipynb
+            - notebooks/multi-level_regression.ipynb
+            - notebooks/sleepstudy.ipynb
+            - notebooks/radon_example.ipynb
+            - notebooks/Strack_RRR_re_analysis.ipynb
+            - notebooks/shooter_crossed_random_ANOVA.ipynb
+            - notebooks/t_regression.ipynb
+        - section: Generalized linear models
+          contents:
+              - notebooks/logistic_regression.ipynb
+              - notebooks/model_comparison.ipynb
+              - notebooks/hierarchical_binomial_bambi.ipynb
+              - notebooks/alternative_links_binary.ipynb
+              - notebooks/wald_gamma_glm.ipynb
+              - notebooks/negative_binomial.ipynb
+              - notebooks/beta_regression.ipynb
+              - notebooks/categorical_regression.ipynb
+              - notebooks/circular_regression.ipynb
+              - notebooks/quantile_regression.ipynb
+        - section: More advanced models
+          contents:
+            - notebooks/distributional_models.ipynb
+            - notebooks/hsgp_1d.ipynb
+            - notebooks/hsgp_2d.ipynb
+        - section: Tools to interpret model outputs
+          contents:
+              - notebooks/plot_predictions.ipynb
+              - notebooks/plot_comparisons.ipynb
+              - notebooks/plot_slopes.ipynb
+
+quartodoc:
+  style: pkgdown
+  dir: api
+  package: bambi # the name used to import the package
+  sidebar: api/_sidebar.yml # write sidebar data to this file
+  sections:
+    - title: Model
+      desc: The basics
+      contents:
+        - Model
+        - Formula
+    - title: Setting up priors
+      desc: ""
+      contents:
+        - Prior
+    - title: Custom families
+      desc: ""
+      contents:
+        - Family
+        - Likelihood
+        - Link
+    - title: Plots
+      desc: ""
+      contents:
+        - interpret.plot_comparisons
+        - interpret.plot_predictions
+        - interpret.plot_slopes
+    - title: Interpretations
+      desc: ""
+      contents:
+        - interpret.comparisons
+        - interpret.predictions
+        - interpret.slopes
+    - title: Data
+      desc: ""
+      contents:
+        - clear_data_home
+        - load_data
+
+
+# Tell quarto to read the generated sidebar
+metadata-files:
+  - api/_sidebar.yml
+
+# filters:
+#   - interlinks
+
+# interlinks:
+#   sources: {}
+
+# profile:
+#   default: latest
+
+format:
+  html:
+    theme: cosmo
+    css: styles.css
+    toc: true
+
+
+# https://github.com/quarto-dev/quarto-web/tree/main/docs/gallery