machow · machow · Apr 15, 2025 · Dec 5, 2024 · Dec 5, 2024 · Apr 15, 2025
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -98,6 +98,9 @@ jobs:
           python -m pip install shiny shinylive
           python -m pip install --no-deps dascore==0.0.8
       - uses: quarto-dev/quarto-actions/setup@v2
+      - name: Test building starter template
+        run: |
+          make test-overview-template
       - name: Build docs
         run: |
           make docs-build

diff --git a/Makefile b/Makefile
@@ -50,4 +50,7 @@ docs-build: docs-build-examples
 	cd docs && quarto add --no-prompt ..
 	quarto render docs
 
+test-overview-template:
+	python scripts/build_tmp_starter.py
+
 test-interlinks: quartodoc/tests/example_interlinks/test.md
diff --git a/README.md b/README.md
@@ -1,5 +1,6 @@
 # Overview
 
+
 [![CI](https://github.com/machow/quartodoc/actions/workflows/ci.yml/badge.svg)](https://github.com/machow/quartodoc/actions/workflows/ci.yml)
 
 **quartodoc** lets you quickly generate Python package API reference
@@ -11,6 +12,7 @@ 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>
@@ -30,16 +32,14 @@ or from GitHub
 python -m pip install git+https://github.com/machow/quartodoc.git
 ```
 
-<div>
-
-> **Install Quarto**
+> [!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.
 
-</div>
-
 ## Basic use
 
 Getting started with quartodoc takes two steps: configuring quartodoc,
@@ -54,21 +54,29 @@ you need to add a `quartodoc` section to the top level your
 `_quarto.yml` file. Below is a minimal example of a configuration that
 documents the `quartodoc` package:
 
+<!-- Starter Template -->
+
 ``` yaml
 project:
   type: website
 
 # tell quarto to read the generated sidebar
 metadata-files:
-  - _sidebar.yml
+  - reference/_sidebar.yml
 
+# tell quarto to read the generated styles
+format:
+  html:
+    css:
+      - reference/_styles-quartodoc.css
 
 quartodoc:
   # the name used to import the package you want to create reference docs for
   package: quartodoc
 
-  # write sidebar data to this file
-  sidebar: _sidebar.yml
+  # write sidebar and style data
+  sidebar: reference/_sidebar.yml
+  css: reference/_styles-quartodoc.css
 
   sections:
     - title: Some functions

diff --git a/docs/get-started/overview.qmd b/docs/get-started/overview.qmd
@@ -71,26 +71,29 @@ Getting started with quartodoc takes two steps: configuring quartodoc, then gene
 
 You can configure quartodoc alongside the rest of your Quarto site in the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html) file you are already using for Quarto.  To [configure quartodoc](./basic-docs.qmd#site-configuration), you need to add a `quartodoc` section to the top level your `_quarto.yml` file.  Below is a minimal example of a configuration that documents the `quartodoc` package:
 
+<!-- Starter Template -->
+
 ```yaml
 project:
   type: website
 
 # tell quarto to read the generated sidebar
 metadata-files:
-  - api/_sidebar.yml
+  - reference/_sidebar.yml
 
 # tell quarto to read the generated styles
 format:
-  css:
-    - api/_styles-quartodoc.css
+  html:
+    css:
+      - reference/_styles-quartodoc.css
 
 quartodoc:
   # the name used to import the package you want to create reference docs for
   package: quartodoc
 
   # write sidebar and style data
-  sidebar: api/_sidebar.yml
-  css: api/_styles-quartodoc.css
+  sidebar: reference/_sidebar.yml
+  css: reference/_styles-quartodoc.css
 
   sections:
     - title: Some functions

diff --git a/scripts/build_tmp_starter.py b/scripts/build_tmp_starter.py
@@ -0,0 +1,32 @@
+import re
+import tempfile
+import subprocess
+from pathlib import Path
+from quartodoc.__main__ import build
+
+p = Path("docs/get-started/overview.qmd")
+overview = p.read_text()
+
+indx = overview.index("<!-- Starter Template -->")
+yml_blurb = overview[indx:]
+
+match = re.search(r"```yaml\s*(.*?)```", yml_blurb, re.DOTALL)
+if match is None:
+    raise Exception()
+
+template = match.group(1)
+
+with tempfile.TemporaryDirectory() as tmpdir:
+    tmpdir = Path(tmpdir)
+    # Write the template to a file
+    p_quarto = tmpdir / "_quarto.yml"
+    p_quarto.write_text(template)
+
+    try:
+        build(["--config", str(p_quarto), "--filter", "quartodoc"])
+    except SystemExit as e:
+        if e.code != 0:
+            raise Exception() from e
+    subprocess.run(["quarto", "render", str(p_quarto.parent)])
+
+    print("SITE RENDERED SUCCESSFULLY")