Add GH pages for docs

.github/workflows/ci.yml

@@ -110,58 +110,3 @@ jobs:
       - name: Build docs
         run: |
           make docs-build
-      # push to netlify -------------------------------------------------------
-      # set release name ----
-
-      - name: Configure pull release name
-        if: ${{github.event_name == 'pull_request'}}
-        run: |
-          echo "RELEASE_NAME=pr-${PR_NUMBER}" >> $GITHUB_ENV
-        env:
-          PR_NUMBER: ${{ github.event.number }}
-      - name: Configure branch release name
-        if: ${{github.event_name != 'pull_request'}}
-        run: |
-          # use branch name, but replace slashes. E.g. feat/a -> feat-a
-          echo "RELEASE_NAME=${GITHUB_REF_NAME/\//-}" >> $GITHUB_ENV
-      # deploy ----
-      - name: Create Github Deployment
-        uses: bobheadxi/deployments@v0.4.3
-        id: deployment
-        with:
-          step: start
-          token: ${{ secrets.GITHUB_TOKEN }}
-          env: ${{ env.RELEASE_NAME }}
-          ref: ${{ github.head_ref }}
-          transient: true
-          logs: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
-
-      - name: Netlify docs preview
-        run: |
-          npm install -g netlify-cli
-          # push main branch to production, others to preview --
-          if [ "${ALIAS}" == "main" ]; then
-            netlify deploy --dir=docs/_build --alias="main"
-          else
-            netlify deploy --dir=docs/_build --alias="${ALIAS}"
-          fi
-        env:
-          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
-          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
-          ALIAS: ${{ steps.deployment.outputs.env }}
-
-      - name: Update Github Deployment
-        uses: bobheadxi/deployments@v0.4.3
-        if: ${{ always() }}
-        with:
-          step: finish
-          token: ${{ secrets.GITHUB_TOKEN }}
-          status: ${{ job.status }}
-          deployment_id: ${{ steps.deployment.outputs.deployment_id }}
-          env_url: "https://${{ steps.deployment.outputs.env }}--quartodoc.netlify.app"
-          logs: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
-      - uses: peaceiris/actions-gh-pages@v3
-        if: github.event_name == 'release'
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/_build

.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches: ["main"]
+
+# needed for peaceiris/actions-gh-pages to push the gh-pages branch
+permissions:
+  contents: write
+
+# never let two deploys race each other onto gh-pages
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: true
+
+jobs:
+  deploy-docs:
+    name: "Build and deploy docs"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Set up Python 3.10
+        run: uv python install 3.10
+      - name: Install dependencies
+        run: |
+          uv sync --group dev
+          # TODO: temporary installs for examples
+          # once quartodoc is stable we should move into their own libraries
+          uv pip install shiny shinylive
+          uv pip install --no-deps dascore==0.0.8
+      - uses: quarto-dev/quarto-actions/setup@v2
+      - name: Build docs
+        run: |
+          make docs-build
+      - name: Deploy to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build
+          publish_branch: gh-pages

.gitignore

@@ -106,13 +106,6 @@ ipython_config.py
 #   are the source of truth, and uv regenerates this on every sync
 uv.lock
 
-# `make docs-build-readme` renders into the repo root, leaving these behind
-# alongside the README it generates
-/index.html
-/objects.json
-/objects.txt
-/objects-test.txt
-
 # PEP 582; used by e.g. github.com/David-OConnor/pyflow
 __pypackages__/
 

Makefile

@@ -1,9 +1,5 @@
 EXAMPLE_INTERLINKS=quartodoc/tests/example_interlinks
 
-README.md: README.qmd
-	quarto render $<
-
-
 # These 2 rules are used to generate the example_interlinks folder,
 # which contains a full example for the interlinks filter to be tested
 
@@ -18,17 +14,6 @@ $(EXAMPLE_INTERLINKS)/test.md: $(EXAMPLE_INTERLINKS)/test.qmd _extensions/interl
 
 
 
-docs-build-readme: export BUILDING_README = 1
-docs-build-readme:
-	# note that the input file is named GITHUB.qmd, because quart does not
-	# render files named README.qmd, and it is very cumbersome to work around
-	# this very strange behavior
-	cd docs \
-	  && quarto render GITHUB.qmd \
-	     --to gfm \
-		 --output README.md \
-		 --output-dir ..
-
 docs-build: export PLUM_SIMPLE_DOC=1
 docs-build:
 	cd docs && uv run quartodoc build --verbose

README.md

@@ -1,16 +1,12 @@
-# Overview
-
 **quartopydoc** lets you quickly generate Python package API reference documentation using Markdown and [Quarto](https://quarto.org). It is designed as an alternative to [Sphinx](https://www.sphinx-doc.org/en/master/).
 
-`quartopydoc` is a fork of [`quartodoc`](https://github.com/machow/quartodoc), created by Michael Chow at Posit but no longer maintained. Only the name of the distribution differs: you still import `quartodoc`, still run `quartodoc build`, and still configure a `quartodoc:` section in your `_quarto.yml`. For what this fork adds on top, see [differences from quartodoc](#differences-from-quartodoc). For Posit's more modern document generation package that is a successor to `quartodoc`, see [Great Docs](https://posit-dev.github.io/great-docs/).
+`quartopydoc` is a fork of [`quartodoc`](https://github.com/machow/quartodoc), created by Michael Chow at Posit but no longer maintained. Only the name of the distribution differs: you still import `quartodoc`, still run `quartodoc build`, and still configure a `quartodoc:` section in your `_quarto.yml`. For what this fork adds on top, see [differences from quartodoc](#differences-from-quartodoc). For Posit’s more modern document generation package that is a successor to `quartodoc`, see [Great Docs](https://posit-dev.github.io/great-docs/).
 
 Check out the below screencast for a walkthrough of creating a documentation site, or read on for instructions.
 
 <p align="center">
 
-<a href="https://www.loom.com/share/fb4eb736848e470b8409ba46b514e2ed">
-<img src="https://cdn.loom.com/sessions/thumbnails/fb4eb736848e470b8409ba46b514e2ed-00001.gif" width="75%">
-</a>
+<a href="https://www.loom.com/share/fb4eb736848e470b8409ba46b514e2ed"> <img src="https://cdn.loom.com/sessions/thumbnails/fb4eb736848e470b8409ba46b514e2ed-00001.gif" width="75%"> </a>
 </p>
 
 <br>
@@ -29,11 +25,7 @@ python -m pip install git+https://github.com/sciris/quartopydoc.git
 
 Note that the package is installed as `quartopydoc`, but imported as `quartodoc`.
 
-> [!IMPORTANT]
->
-> ### Install Quarto
->
-> If you haven’t already, you’ll need to [install Quarto](https://quarto.org/docs/get-started/) before you can use quartodoc.
+> **Important:** if you haven’t already, you’ll need to [install Quarto](https://quarto.org/docs/get-started/) before you can use quartodoc.
 
 ## Basic use
 

docs/_quarto.yml

@@ -31,6 +31,8 @@ interlinks:
 
 website:
   title: "quartopydoc"
+  site-url: https://sciris.github.io/quartopydoc/
+  repo-url: https://github.com/sciris/quartopydoc/
   page-navigation: true
   navbar:
     left: