Build the docs with great-docs

.agents/agents.md

@@ -42,16 +42,18 @@ pytest dascore --doctest-modules
 
 ## Docs
 
-- `.qmd` under `docs/`; API docs come from docstrings. Update with any behavior or API change. Do not hard-wrap prose.
-- Edit `scripts/_templates/_quarto.yml` for site structure; `docs/_quarto.yml` is generated.
+- `.qmd` in the top-level section directories (`tutorial/`, `recipes/`, `notes/`, `contributing/`, `about/`), with `index.qmd` as the landing page. API docs come from docstrings. Update with any behavior or API change. Do not hard-wrap prose.
+- Site structure, styling and the curated API reference are configured in `great-docs.yml`; the `great-docs/` directory is generated. New public API needs a reference entry, and `tests/test_doc_coverage.py` fails when it has none.
 
 ```bash
-python scripts/build_api_docs.py && quarto render docs
+pip install "great-docs>=0.16"
+great-docs build      # writes great-docs/_site
+great-docs preview    # serves the built site
 ```
 
 ### Changelog
 
-No changelog file, and do not add one — no `CHANGELOG.md`, `changelog.d/`, or "unreleased" sections. `docs/changelog.qmd` is a stub pinned by `tests/test_changelog.py`. Put the summary in the PR's required `## Changelog` section, formatted per "Changelog entries" in `docs/contributing/general_guidelines.qmd`; `.github/scripts/check_pr_changelog.py` is the parser CI runs.
+No changelog file, and do not add one — no `CHANGELOG.md`, `changelog.d/`, or "unreleased" sections; the site's changelog page is generated from the GitHub releases at build time, and `tests/test_changelog.py` fails if a source page appears. Put the summary in the PR's required `## Changelog` section, formatted per "Changelog entries" in `contributing/general_guidelines.qmd`; `.github/scripts/check_pr_changelog.py` is the parser CI runs.
 
 ## Before handing off
 

.github/actions/build-docs/action.yml

@@ -1,13 +1,31 @@
 name: "Build DASCore Docs"
-description: "Builds DASCore's Documentation."
+description: "Builds DASCore's Documentation with great-docs."
 
 runs:
   using: "composite"
   steps:
 
-    - uses: ./.github/actions/prep_doc_build
+    - name: Install quarto
+      uses: quarto-dev/quarto-actions/setup@8a96df13519ee81fd526f2dfca5962811136661b  # v2.2.0
+      with:
+        # 1.3.x dies with "RangeError: Invalid string length" once the
+        # generated API sidebar gets large enough; see
+        # quarto-dev/quarto-cli#10504.
+        version: 1.8.27
 
-    - name: build quarto project
-      shell: bash
+    - name: print quarto version
+      shell: bash -l {0}
       run: |
-        quarto render docs
+        quarto --version
+
+    - name: install great-docs
+      shell: bash -l {0}
+      run: |
+        # >=0.16 renders class signatures with their parameters and points
+        # See Also links at the pages the reference actually generates.
+        python -m pip install "great-docs>=0.16"
+
+    - name: build documentation
+      shell: bash -l {0}
+      run: |
+        great-docs build

.github/workflows/build_deploy_master_docs.yaml

@@ -49,12 +49,17 @@ jobs:
           python-version: ${{ steps.shared-vars.outputs.python-default }}
           prepare-test-data: "true"
 
-      - uses: ./.github/actions/prep_doc_build
+      - uses: ./.github/actions/build-docs
 
       - name: publish docs to netlify
         shell: bash
         env:
-          QUARTO_PRINT_STACK: true
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
         run: |
-            quarto publish docs --no-prompt --no-browser
+            # The site id previously lived in docs/_publish.yml, which
+            # `quarto publish` read; great-docs emits a plain directory, so
+            # deploy it with netlify's own CLI instead.
+            npx --yes netlify-cli@23 deploy \
+              --prod --no-build \
+              --dir great-docs/_site \
+              --site da79b12f-cb25-4fcc-aeb6-f19705848130

.github/workflows/build_deploy_stable_docs.yaml

@@ -81,11 +81,11 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5.0.0
         with:
-          path: 'docs/_site'
+          path: 'great-docs/_site'
 
       - name: Zip doc build
         if: startsWith(github.ref, 'refs/tags/')
-        run: zip docs.zip docs/_site -r
+        run: zip docs.zip great-docs/_site -r
 
       - name: Upload release docs
         if: startsWith(github.ref, 'refs/tags/')

.github/workflows/test_doc_build.yml

@@ -49,7 +49,9 @@ jobs:
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: documentation_build_test
-          path: ./docs/_site
+          path: ./great-docs/_site
+          # .well-known/agent-skills must survive packaging
+          include-hidden-files: true
           retention-days: 1
 
       - name: Generate documentation URL

.gitignore

@@ -52,9 +52,6 @@ coverage.xml
 # logs:
 *.log
 
-# Sphinx documentation
-docs/_build/
-
 # PyBuilder
 target/
 
@@ -70,12 +67,9 @@ target/
 .DS_store*
 
 # docs
-docs/api/*
 _autosummary
 .quarto/
-docs/site_libs
-docs/_quarto.yml
-docs/**/*.ipynb
+**/*.quarto_ipynb
 .cross_ref.json
 
 # profile stuff from asv
@@ -88,8 +82,7 @@ scratch/**
 uv.lock
 tests/test_autogenerated_doccode/
 
-docs/index_files
-docs/index.quarto_ipynb
+index_files/
 
 # Agent stuff
 .codex
@@ -114,3 +107,6 @@ prof/
 .vscode/
 #JetBrains
 .idea/
+great-docs/
+# Quarto freeze cache written by great-docs builds.
+_freeze/

.pre-commit-config.yaml

@@ -1,4 +1,3 @@
-exclude: scripts/_templates
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v2.3.0

docs/acknowledgements.qmd → about/acknowledgements.qmd

@@ -1,10 +1,10 @@
 ---
+title: Acknowledgments
+description: "Funding sources and acknowledgments."
 ---
 
 <!--
 Add major acknowledgments here, funding sources, etc.
 -->
 
-# Acknowledgments
-
 - DASDAE is supported in part by the NSF Geoinformatics Program, under grant [#2148614](https://nsf.gov/awardsearch/showAward?AWD_ID=2148614)

docs/contributors.qmd → about/contributors.qmd

@@ -1,3 +1,6 @@
-# Contributors
+---
+title: Contributors
+description: "Thanks to everyone who has contributed to DASCore."
+---
 
 A huge thanks to [all the DASCore contributors](https://github.com/DASDAE/dascore/graphs/contributors)!

docs/supported_formats.qmd → about/supported_formats.qmd

@@ -1,5 +1,6 @@
 ---
 title: Supported File Formats
+description: "File formats DASCore can read and write."
 execute:
     warning: false
 ---

docs/supported_plugins.qmd → about/supported_plugins.qmd

@@ -1,5 +1,6 @@
 ---
 title: Supported Third-Party Plugins
+description: "Packages that add namespaces to DASCore's Patch and Spool."
 execute:
     warning: false
 ---