tests: script to test get-started template

Author: machow

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

README.md

@@ -12,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>
@@ -53,6 +54,8 @@ 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
@@ -63,8 +66,9 @@ metadata-files:
 
 # tell quarto to read the generated styles
 format:
-  css:
-    - reference/_styles-quartodoc.css
+  html:
+    css:
+      - reference/_styles-quartodoc.css
 
 quartodoc:
   # the name used to import the package you want to create reference docs for

docs/get-started/overview.qmd

@@ -71,6 +71,8 @@ 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
@@ -81,8 +83,9 @@ metadata-files:
 
 # tell quarto to read the generated styles
 format:
-  css:
-    - reference/_styles-quartodoc.css
+  html:
+    css:
+      - reference/_styles-quartodoc.css
 
 quartodoc:
   # the name used to import the package you want to create reference docs for

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")