Merge pull request #142 from posit-dev/docs-authoring-guide

docs: add authoring page to User Guide

Author: rich-iannone

.github/workflows/docs.yml

@@ -23,7 +23,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install -e .
-          python -m pip install jupyter polars pandas pyarrow
+          python -m pip install jupyter polars pandas pyarrow plotnine
 
       - name: Set up Quarto
         uses: quarto-dev/quarto-actions/setup@v2

great-docs.yml

@@ -230,6 +230,7 @@ nav_icons:
     Welcome to Great Docs: compass
     Installation: download
     Quick Start: rocket
+    Authoring QMD Files: file-pen
     Configuration: settings
     Theming & Appearance: palette
     Content & API: file-text

pyproject.toml

@@ -62,6 +62,7 @@ dev = [
 ]
 docs = [
     "jupyter>=1.0.0",
+    "plotnine>=0.13.0",
 ]
 
 

recipes/15-build-site-with-llm.qmd

@@ -71,6 +71,6 @@ The agent *cannot* install Python or Quarto, publish your package to PyPI, confi
 
 ## Tips for effective prompts
 
-Be specific about what you want rather than asking for "a good documentation site." A prompt like "add a user guide page about caching that explains TTL, LRU, and invalidation strategies" gives the agent enough context to produce useful content on the first try. If the result needs adjustment, follow up with targeted corrections like "move the LRU section before TTL" rather than asking the agent to start over.
+Be specific about what you want rather than asking for "a good documentation site". A prompt like "add a user guide page about caching that explains TTL, LRU, and invalidation strategies" gives the agent enough context to produce useful content on the first try. If the result needs adjustment, follow up with targeted corrections like "move the LRU section before TTL" rather than asking the agent to start over.
 
 When making multiple changes, ask for one change at a time and rebuild between each step. This makes it easy to spot which change caused an issue if something goes wrong.

user_guide/02-quickstart.qmd

@@ -200,7 +200,9 @@ docs.build()
 
 ## What's Next?
 
-Your documentation site is ready! Here's what to explore next:
+Your documentation site is ready! If you're new to writing `.qmd` files, head to the [Authoring QMD Files](authoring-qmd-files.qmd) guide for a thorough introduction to Markdown, frontmatter, callouts, tabsets, and all the other building blocks available to you.
+
+From there, explore these topics to take your site further:
 
 - [Configuration](configuration.qmd) covers customizing Great Docs behavior
 - [API Documentation](api-documentation.qmd) explains how API discovery works