docs: Build README.md from docs/index.qmd (#40)

.github/workflows/pytest.yaml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
         os: [ubuntu-latest, windows-latest, macOS-latest]
       fail-fast: false
     defaults:

.github/workflows/quartodoc.yaml

@@ -87,3 +87,11 @@ jobs:
 
           # Deploy site by pushing to gh-pages
           git push origin gh-pages
+
+      - name: Check that README.md is up-to-date
+        run: |
+          make docs-readme
+          if git diff --name-only HEAD | grep -q 'README.md'; then
+            echo '::error file=README.md,title=README is out-of-date::README.md is out of date. Please run `make docs-readme` to update it.'
+            exit 1
+          fi

Makefile

@@ -82,10 +82,12 @@ docs-render-ci: quarto-shinylive
 docs-watch: quarto-shinylive
 	cd docs && quarto preview
 docs-ci: docs-quartodoc docs-render-ci ## Build quartodoc for CI
+docs-readme: README.md ## Build README.md from index.qmd
+	quarto render docs/index.qmd --output README.md --output-dir . --profile readme
 docs-preview: docs-quartodoc docs-watch ## Build quartodoc for preview
 docs-open:
 	$(BROWSER) docs/_site/index.html
-docs: docs-ci docs-open ## generate quartodoc HTML documentation, including API docs
+docs: docs-readme docs-ci docs-open ## generate quartodoc HTML documentation, including API docs
 
 # # Perform `quarto preview` and `quartodoc build` in parallel
 # watchdocs: quarto-shinylive

README.md

@@ -1,32 +1,35 @@
 # shinyswatch
 
-[Bootswatch](https://bootswatch.com/) + Bootstrap 5 themes for [Shiny](https://shiny.rstudio.com/py/).
 
+<!-- DO NOT EDIT BY HAND: Edit docs/index.qmd and run `make docs-readme` to update -->
+
+[Bootswatch](https://bootswatch.com/) + Bootstrap 5 themes for
+[Shiny](https://shiny.rstudio.com/py/).
 
 Here are just three of the **25 themes** in shinyswatch:
 
-| Minty                      | Sketchy                        | Superhero                          |
-|----------------------------|--------------------------------|------------------------------------|
+| Minty                                                                                      | Sketchy                                                                                        | Superhero                                                                                          |
+|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
 | ![Minty](https://raw.githubusercontent.com/rstudio/py-shinyswatch/v0.2.2/readme_minty.png) | ![Sketchy](https://raw.githubusercontent.com/rstudio/py-shinyswatch/v0.2.2/readme_sketchy.png) | ![Superhero](https://raw.githubusercontent.com/rstudio/py-shinyswatch/v0.2.2/readme_superhero.png) |
 
-
 ## Installation
 
-```sh
+``` sh
 pip install shinyswatch
 ```
 
 To install the latest development version from this repository:
 
-```sh
+``` sh
 pip install https://github.com/rstudio/py-shinyswatch/tarball/main
 ```
 
 ## Usage
 
-To use a theme, call the theme function and add it to your App's UI definition.
+To use a theme, add a `shinyswatch.theme` theme object to your App’s UI
+definition.
 
-```python
+``` python
 # Minty theme
 shinyswatch.theme.minty
 
@@ -40,23 +43,29 @@ shinyswatch.theme.superhero
 Example Shiny application:
 
 <table>
-    <thead><tr>
-        <th>File: <code>app.py</code></th>
-        <th>Screenshot</th>
-    </tr></thead>
-    <tbody><tr><td>
-
-```python
+<thead>
+<tr>
+<th>
+File: <code>app.py</code>
+</th>
+<th>
+Screenshot
+</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+``` python
 from shiny import App, Inputs, Outputs, Session, render, ui
 
 import shinyswatch
 
 app_ui = ui.page_fluid(
-    # Theme code - start
-    shinyswatch.theme.darkly,
-    # Theme code - end
     ui.input_slider("num", "Number:", min=10, max=100, value=30),
     ui.output_text_verbatim("slider_val"),
+    theme=shinyswatch.theme.darkly,  # <- Use a shinyswatch theme here
 )
 
 
@@ -70,27 +79,43 @@ def server(input: Inputs, output: Outputs, session: Session):
 app = App(app_ui, server)
 ```
 
-</td><td>
+</td>
+<td>
+
+![darkly
+theme](https://raw.githubusercontent.com/rstudio/py-shinyswatch/v0.2.2/readme_darkly.png)
 
-![darkly theme](https://raw.githubusercontent.com/rstudio/py-shinyswatch/v0.2.2/readme_darkly.png)
+</td>
+</tr>
+</tbody>
+</table>
 
-</td></tr></tbody></table>
+> Note: When writing [shiny apps that use shinyswatch on
+> shinylive.io](https://shinylive.io/py/editor/#code=NobwRAdghgtgpmAXAAjFADugdOgnmAGlQGMB7CAFzkqVQDMAnUmZAZwAsBLCXZTmdKQYVkAQUxEAkhHQBXCqyIB5eXIVEAynFatO5Ig2oATOAyKzOAHQjX+g4Wy49WAdygVi7a9YzoA+hbIALzIFjhQAOZwfnQANhZGABTWyKmhnFjcan6ssZwmDMmQsjCWhMhlAHIlAEamiGVEMNxBAIwADE1QAB5t7Z3IAG5Q8XBBAMztAJQEKWlhpKryflTdFH6DpjXu-EW5+aYbI2Uzc6kU7HDwQRzcuK7unlgXV3BYRlAMANaxuETIAGJkAAeAC0yAAqqw4MgoI47g8POxkC94MhLoZrFNvDYICY6GxTJtCll5ChpGpFMhFhQ1CgVLT5FToTo9BAUFpWeQpg0IGlkAABGlqM6Cwx40zPOBrUX4th5ApHWKJHmi-mGCiyBh8uhlECkihYCAlFUAXzKOJ8mGCYkwiV8AU4RGhDGJ2Ig5TAFFw6AQKC90ooYFNRHA0HgtDAhgAjhZDPBKKxnmtPWRKNQg-7bjxrNn7m4kdZPd7fZHVkHTQBdIA),
+> remember to add `shinyswatch` to your `requirements.txt` file!
 
-> Note: When writing shiny apps on [shinylive.io](https://shinylive.io/py/editor/#code=NobwRAdghgtgpmAXGKAHVA6VBPMAaMAYwHsIAXOcpMAMwCdiYACAZwAsBLCbJjmVYnTJMAgujxM6lACZw6EgK4cAOhD4ChrTtxYB3KGUJtVqtKgD6SpgF4mSrFADmcczQA2S6QApVTP1q5sPQMjDDI2OHgMAC84VDZseV9-ey5UBTJzFjcOWTofSGV8JiKAOSKJAAYJAEZK6qYAJkqASjxkv3tiDPTMigAPTIA3OQAjAz4CskGittUWkwhVWRpWORH8tIyJbrJeiRY4FhYOUhbEDqYAAV3ey6upCDywuBmIfyYVpmmyL3PLj5SMgKOjvGhFCAAKkavBYTBAWzIGAgfyYkKaAF8iotTOgbKJ0F4zJYOAd1nIFhAwBi8OBoPBqFIAI5KKTwcgsMKDfBEUgUKjIdiBYKGNjUgC6QA), remember to add `shinyswatch` to your `requirements.txt` file!
+## Theme picker
 
-### Theme picker
+To add a theme picker to your app, add the theme picker UI and server
+functions to your app’s UI and server definitions.
 
-To add a theme picker to your app, add the `shinyswatch.theme_picker_ui()` in place of your theme object and add `shinyswatch.theme_picker_server()` into your `server` definition.
+[Demo **theme picker** app on
+shinylive.io](https://shinylive.io/py/editor/#code=NobwRAdghgtgpmAXAAjFADugdOgnmAGlQGMB7CAFzkqVQDMAnUmZAZwAsBLCXZTmdKQYVkAQUxEAkhHQBXCqyIB5eXIVEAynFatO5Ig2oATOAyKzOAHQjX+g4Wy49WAdygVi7a9YzoA+hbIALzIFjhQAOZwfnQANhZGABTWyKmO3Liu7p5YFOxw8H7onMQA1qYBnIkAlETIAMTIADwAtGJGRsh5cF358MjFZabIAKqSXaTIuKSyDMi+KWlh3Gp+rLGcJgzJkLIwloTIBwByewBGpogHRDDcQQCMAAw3UAAeD4-PyABuUPFwQQAzI9aotUmEZhRVlRXhQ-N9TGd3PwdutNhVfrEDqCIGlegUARwMlkPOxcn04FgAF5wdDsXBmVKNVrIADC7FIpFYPSguO4nAonD++P6iVI6EF5D+1WsMps8pMdDYpgR2xW8hQ0jUimQkLUKBUUPkOu5Oj0EBQWjN5GqV1xaUaAFkoOU2LMetNZsqGKrkHRZBBiJLccQ-rFWPiRT1BuU5tyfcN-YHg2D0s43KTyQSiiVY2sVaYat57akAAJ6+Sp0uGCBbXJwWGpxVsDZbeF-Gp2vF4wwUWa4ugHEDqihYCB7GoAXwOxZ8mGCYkwiV8lSI8dVcsOYAouHQCBQ24bFDAk6I4Gg8FoYEMAEcLIZ4JRWLlYVuyJRqMeD0SeNYf5kM08awtx3PcrxhY9JwAXSAA).
 
-Demo: [shinylive.io](https://shinylive.io/py/editor/#code=NobwRAdghgtgpmAXGKAHVA6VBPMAaMAYwHsIAXOcpMAMwCdiYACAZwAsBLCbJjmVYnTJMAgujxMAkhFQBXMiwkB5eXIUSAynBYsOpCXUoATOHQmyOAHQjW+Aoa07cWAdyhlCba9bSoA+hZMALxMFlhQAOZwfjQANhZGABTWTKlMAMRMACpscPBMqByEANamTAC0rGRQQilp7FzYru6eGGS58H6FJaYBHIkAlHh1qZk5eXAFRaV0FUzGI6EcGFxqfiyxHCZ0yZCyMJb4TIcAcvsARqaIhxIwXEEAjAAMt1AAHo9PL0wAblDxcCCAGYnkNFmFiKp5H4KG8yH4fqZzu4+LsNlten9YocwRABt4bBATDRWKZETtVvJEFIZPJFExIWQ1NSVEy6RIWNpdKRqVodHo8dcIGkMmMOpNujM5ixqrVhfUnE03B42G1xV1pr1OXRyYNFukxRMpj1ZpUFoSRQABRlqRaWwxE0xtOBwxbE1ibbYI-6DIUikWGMiyOjCmiHECUsgYCD7QYAX0OBJ86GConQiV8fQ5ZNM+MJYDjeHA0Hg1EMAEcLIZ4OQWG04fgiKQKFRkA1nMrPAWALpAA)
+## Plot Theming
 
+shinyswatch themes include a `.colors` attribute that can be used to
+theme plots or other outputs and UI elements. In the example below, try
+changing the theme and re-running the app to see how the plot changes.
 
+[Demo **plot theming** app on
+shinylive.io](https://shinylive.io/py/editor/#code=NobwRAdghgtgpmAXAAjFADugdOgnmAGlQGMB7CAFzkqVQEsZ1SAnC5GKC9AG1Iu7oAjHLh59kUAM7IeFADoQGTVsggBXRrgnSI6BQDNmpGMkkALOhC1KWbAIKYizagBM4zJ3ACORNXQUKAMTIACrMWsRmUBAA5pYxyBRmcInJ8MiGxuyWFFoUpMhqilQuBkYm5pa4kgDunJFYSXDpNiowOVpSphZWAPpN8AHQmL1+yAC8hXQ4UDFwvfrcfi4AFArIG1NYluhqFL2SAm7Ma5ByhMjnAHLnRO0Q4wAMd1AAHuMAjI-PyABuUEs4OMAEyPACUBHWmz8WGIUGYqxhpD2u32Ygop3R5zBEKhGwGQMqfQJkIgYKGCjc+lM7l+7hWOz2YMQeOQAAFnBBjjheBiARRxuc7MgLJJ8jFmLBsayqTJeStmazNqpsJKucYsJI4HBVh8AJwANgAHI8TR9yRBlcrXhNkF9HsgANR2gCsyAAVCqsGqXBqfRAVgAWADMAHYLUrNvo6DEiG9bbJNWpBOjJArIxs3lhRRjXkRGRQsAGIcg3BBJHRcuMwmo4EQyLxmOMibh+mk4LDSI3JDhmAx4bgI5arRtgiF26kUujEgUOBRIpPkMQ1MxOWwCRmMjGZvOzJq4Pt9FBiHAGyxThByHBpcOR1mtYfj6eu+fzpeINewEORxsz8wFgkkwtm2zQdn+PaCKQLitn+m5ZhQdDEAA1r06DwrAaZvHQkiCmAkFJLcS4vswOF-gBFo-hIryauglhwJIwDnPh+QwOcAC6+77H+KxkfoMQUT+960R+DHnPkehgBxD69NxvH8XB1GSMJ9GMWA3BwPo8iSZxMnETxxHkQpNF0aJYB9jEZhaVJB66Y2+mNoZECbs4FArpa0YxBSwzoLaDjoCsGDoKMdBEFqzB0swFoXGAuToAgKAxXArwUGAAC+RDgNA8C0GZ3h+M48CUD2FDJdFZCUNQKUJeomgKHO6ICIICgts1PTVHUu4KNFsXxagVClalbFAA).
 
 ## Development
 
 If you want to do development on shinyswatch for Python:
 
-```sh
+``` sh
 pip install -e ".[dev,test,docs]"
 ```
 
@@ -102,7 +127,7 @@ There are multiple examples in the shinyswatch repo.
 
 To run the demos locally, you can run the examples by calling:
 
-```sh
+``` sh
 python3 -m shiny run examples/basic-darkly/app.py
 python3 -m shiny run examples/big-sketchy/app.py
 python3 -m shiny run examples/components/app.py

docs/.gitignore

@@ -6,3 +6,4 @@
 /objects.json
 /_sidebar.yml
 /site_libs/
+/index.html

docs/_quarto-readme.yml

@@ -0,0 +1,4 @@
+project:
+  type: default
+
+format: gfm

docs/examples/darkly/app.py

@@ -0,0 +1,19 @@
+from shiny import App, Inputs, Outputs, Session, render, ui
+
+import shinyswatch
+
+app_ui = ui.page_fluid(
+    ui.input_slider("num", "Number:", min=10, max=100, value=30),
+    ui.output_text_verbatim("slider_val"),
+    theme=shinyswatch.theme.darkly,  # <- Use a shinyswatch theme here
+)
+
+
+def server(input: Inputs, output: Outputs, session: Session):
+    @output
+    @render.text
+    def slider_val():
+        return f"{input.num()}"
+
+
+app = App(app_ui, server)

docs/examples/darkly/requirements.txt

@@ -0,0 +1,2 @@
+shiny
+shinyswatch

docs/examples/plot-theming/app.py

@@ -0,0 +1,38 @@
+import matplotlib.pyplot as plt
+import numpy as np
+from shiny import App, render, req, ui
+
+# Try changing the theme from minty to united
+from shinyswatch.theme import minty as shiny_theme
+
+app_ui = ui.page_fluid(
+    ui.input_slider("n", "N", min=0, max=100, value=20),
+    ui.card(ui.output_plot("plot")),
+    theme=shiny_theme,
+)
+
+
+def server(input):
+    @render.plot(alt="A histogram")
+    def plot():
+        np.random.seed(19680801)
+        x = 100 + 15 * np.random.randn(437)
+
+        fig, ax = plt.subplots()
+        ax.hist(x, input.n(), density=True, color=shiny_theme.colors.primary)
+
+        # Theme the plot to match the current theme
+        fig.patch.set_facecolor("none")
+        ax.set_facecolor("none")
+
+        color_fg = shiny_theme.colors.body_color
+        ax.tick_params(axis="both", colors=color_fg)
+        ax.spines["bottom"].set_color(color_fg)
+        ax.spines["top"].set_color(color_fg)
+        ax.spines["left"].set_color(color_fg)
+        ax.spines["right"].set_color(color_fg)
+
+        return fig
+
+
+app = App(app_ui, server)

docs/examples/plot-theming/requirements.txt

@@ -0,0 +1,4 @@
+numpy
+matplotlib
+shiny
+shinyswatch

docs/examples/theme-picker/app.py

@@ -0,0 +1,23 @@
+from shiny import App, Inputs, Outputs, Session, render, ui
+
+import shinyswatch
+
+app_ui = ui.page_fluid(
+    shinyswatch.theme_picker_ui(),  # <- Add the theme picker UI to your app
+    ui.input_slider("num", "Number:", min=10, max=100, value=30),
+    ui.output_text_verbatim("slider_val"),
+    theme=shinyswatch.theme.zephyr,  # <- Choose an initial theme (optional)
+)
+
+
+def server(input: Inputs, output: Outputs, session: Session):
+    # Make sure your server function calls the theme picker server function
+    shinyswatch.theme_picker_server()
+
+    @output
+    @render.text
+    def slider_val():
+        return f"{input.num()}"
+
+
+app = App(app_ui, server)

docs/examples/theme-picker/requirements.txt

@@ -0,0 +1,2 @@
+shiny
+shinyswatch