basic documentation using quartodoc

.gitignore

@@ -136,3 +136,5 @@ dmypy.json
 
 # Cython debug symbols
 cython_debug/
+
+/.quarto/

README.md

@@ -1,39 +1,4 @@
 # quarto-python
 
-Python interface to the Quarto CLI (https://quarto-dev/quarto-cli). 
-
-
-
-## theme helpers
-
-`quarto-python` contains theme helpers to do basic background/foreground theming of plots and tables
-
-The `theme_colors_*` functions take background and foreground colors:
-
-| parameter | description |
-| --------- | ----------- |
-| `bg` | background color |
-| `fg` | foreground color |
-
-The `theme_brand_*` functions take a [brand.yml](https://posit-dev.github.io/brand-yml/) file:
-
-| parameter | description |
-| --------- | ----------- |
-| `brand_yml` | path to **brand.yml** file |
-
-Available theme helpers:
-
-| colors | brand |
-| --------- | ----------- |
-| `theme_colors_altair` | `theme_brand_altair` |
-| `theme_colors_bokeh` | `theme_brand_bokeh` |
-| `theme_colors_great_tables` | `theme_brand_great_tables` |
-| `theme_colors_matplotlib` | `theme_brand_matplotlib` |
-| `theme_colors_plotnine` | `theme_brand_plotnine` |
-| `theme_colors_plotly` | `theme_brand_plotly` |
-| `theme_colors_pygal` | `theme_brand_pygal` |
-| `theme_colors_seaborn` | `theme_brand_seaborn` |
-
-The usage of the returned object or function depends on the package. See this repo for usage examples:
-
-https://github.com/quarto-dev/quarto-examples/tree/main/renderings
+Python interface to the Quarto CLI (https://quarto-dev/quarto-cli),
+and helper functions for use inside Quarto documents.

_quarto.yml

@@ -0,0 +1,61 @@
+project:
+  type: website
+
+# tell quarto to read the generated sidebar
+metadata-files:
+  - 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: quarto
+
+  # write sidebar and style data
+  sidebar: reference/_sidebar.yml
+  css: reference/_styles-quartodoc.css
+
+  sections:
+    - title: Quarto functions
+      # desc: Helper functions to apply background/foreground theming of plots and tables.
+      contents:
+        - dynamic: true
+          name: path
+          # desc: Returns the path to the Quarto executable.
+        - dynamic: true
+          name: render
+          # desc: Renders a Quarto document.
+        - dynamic: true
+          name: metadata
+        - kind: page
+          summary:
+            name: theme helpers
+            desc: |
+              `theme_colors_*` functions take background and foreground colors.
+
+              `theme_brand_*` functions take a [brand.yml](https://posit-dev.github.io/brand-yml/) file.
+
+              The usage of the returned object or function depends on the package. See the [`quarto-examples` repo
+              for usage examples](https://github.com/quarto-dev/quarto-examples/tree/main/renderings).
+          path: theme_helpers
+          contents:
+            - theme_colors_altair
+            - theme_brand_altair
+            - theme_colors_bokeh
+            - theme_brand_bokeh
+            - theme_colors_great_tables
+            - theme_brand_great_tables
+            - theme_colors_matplotlib
+            - theme_brand_matplotlib
+            - theme_colors_plotnine
+            - theme_brand_plotnine
+            - theme_colors_plotly
+            - theme_brand_plotly
+            - theme_colors_pygal
+            - theme_brand_pygal
+            - theme_colors_seaborn
+            - theme_brand_seaborn

quarto/metadata.py

@@ -6,6 +6,7 @@
 from quarto.quarto import find_quarto
 
 def metadata(input):
+  """Return the metadata for a Quarto document."""
   args = ["metadata", input, "--json"]
   metadata_json = subprocess.check_output([find_quarto()] + args)
   return json.loads(metadata_json)

quarto/quarto.py

@@ -5,6 +5,7 @@
 import subprocess
 
 def path():
+  """Return the path to the Quarto executable."""
   path_env = os.getenv("QUARTO_PATH")
   if path_env is None:
     return shutil.which("quarto")

quarto/render.py

@@ -20,7 +20,7 @@ def render(input,
            debug = False,
            quiet = False,
            pandoc_args = None):
-
+  """Render a Quarto document."""
   # params file to remove after render
   params_file = None