Add Great Docs site (including workflow file) (#11)

* Create user guide article .qmd files

* Move benchmarks.qmd to dedicated directory

* Delete _quarto.yml

* Remove docs directory

* Add Great Docs config file

* Add docs dir with .gitignore and _quarto.yml

* Create docs.yml

* Ensure that Great Docs is installed in workflow

* Update docs workflow to use maturin for build

* Update docs workflow to build and install wheel

* Update tag assertion in YAML parsing example

* Update .gitignore

* Remove generated Quarto docs files

* Delete mkdocs.yml

* Delete 10-reference.qmd

* Switch docs build to great-docs

* Rename Source URL to Repository

* Update great-docs.yml config

* Create 00-index.qmd

* Update contributing guide: Great Docs & tests

* Update docs workflow to use great-docs/_site

* Revise User Guide intro and update links

Author: rich-iannone

.github/workflows/docs.yml

@@ -0,0 +1,111 @@
+name: CI Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build-docs:
+    name: "Build Docs"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build and install package
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --out dist
+          sccache: true
+
+      - name: Install package and documentation dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install dist/*.whl
+          python -m pip install git+https://github.com/rich-iannone/great-docs.git
+          python -m pip install quartodoc jupyter
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Build docs
+        run: great-docs build
+
+      - name: Save docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: great-docs/_site
+
+  publish-docs:
+    name: "Publish Docs"
+    runs-on: ubuntu-latest
+    needs: "build-docs"
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: great-docs/_site
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: great-docs/_site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+  preview-docs:
+    name: "Preview Docs"
+    runs-on: ubuntu-latest
+    needs: "build-docs"
+    if: github.event_name == 'pull_request'
+    permissions:
+      deployments: write
+      pull-requests: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: great-docs/_site
+
+      # Start deployment
+      - 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@v1
+        id: deployment
+        if: ${{ !github.event.pull_request.head.repo.fork }}
+        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 }}"

.gitignore

@@ -77,3 +77,6 @@ site/
 
 /.quarto/
 **/*.quarto_ipynb
+
+# Great Docs build directory (ephemeral)
+great-docs/

README.md

@@ -142,15 +142,11 @@ assert round_tripped == obj
 
 Online docs: https://posit-dev.github.io/py-yaml12/
 
-- Guides: `docs/usage.md` (basics) and `docs/tags.md` (advanced tags,
-  anchors, streams).
-- Reference: `docs/reference/`.
-- API overview: `docs/api.md`.
-
 To build or serve the docs locally:
 
 ```bash
-.venv/bin/mkdocs build        # or: .venv/bin/mkdocs serve
+pip install git+https://github.com/rich-iannone/great-docs.git
+great-docs build       # or: great-docs preview
 ```
 
 ## Tests